Welcome to Agilent VEE Pro

Welcome!

Welcome to Agilent VEE Pro Help. To find a topic you want to read, click on the Contents or Index buttons above.

Agilent VEE Pro 8.5 New Features

What's Been Fixed in this Release

Microsoft®, MS-DOS®, Windows®, MS Windows®, Windows NT®, Excel®, Word®, .NET®, Outlook®, ActiveX®, Visual Basic®, Visual C# ® are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries.

PostScript® is a trademark of Adobe Systems Incorporated.

MATLAB® is a registered trademark of The MathWorks, Inc.

National Instruments®, NI®, LabVIEW® and SCXI® are registered trademarks of National Instruments Corporation.

PXI® is a registered trademark of PXI System Alliance.

IVI® and IVIplug&play® are registered trademarks of the IVI Foundation.

Pentium® is a U.S. registered trademark of Intel Corporation.

Arial® and Times New Roman® are U.S. registered trademarks of the Monotype Corporation.


Agilent VEE Pro 8.5 New Features

The following figure is the default layout of the IDE with the Program Explorer and Properties Window docked on the left side of the workspace, the Function & Object Browser and Instrument Manager docked on the right side with auto-hide, and the Output window and Find Results window docked at the bottom with auto-hide. You can reset to this default layout using Window => Reset Tool Bar / Window layout command at any time.

You can also customize menu items and toolbar buttons as you need and even save and load your own toolbar and tool window layout using Save Tool Bar / Window layout or Load Tool Bar / Window layout command under Window menu at any time.

The following figure shows a custom IDE configuration with Instrument Manager, Function & Object Browser, and Output window floating outside of the Agilent VEE main window.

See Also

To Arrange and Dock Tool Windows Describes how to dock and auto hide tool windows and how to reset your window layout.

To Customize Agilent VEE Toolbar Describes how to change the layout, position, and content of toolbars and how to reset your toolbar layout.

Agilent VEE 8.5 supports Microsoft Windows Vista (32-bit), Windows XP SP2, and Windows 2000 SP4. Please note that Agilent VEE 8.5 only supports Windows Vista Business, Windows Vista Ultimate and Windows Vista Enterprise. Windows Vista Home Basic and Home Premium editions are not supported.

Note: Only 32-bit versions of OS are supported by Agilent VEE.

Installation and uninstallation

Be aware that you must have system administrator capability to install or uninstall Agilent VEE on computers running Windows Vista, Windows XP, or Windows 2000.

Agilent VEE saves configuration files in a per-user and per-version style, which means each user may have more than one set of configuration files, each set corresponding to one version of VEE that is used. See Configuring VEE for Windows for detailed information.

For IO configuration file, if the VEE environment variable exists, Agilent VEE also provides a global configuration file for all users and all editions ( Agilent VEE Pro, Agilent VEE Express, Agilent VEE Student ) per version of Agilent VEE. See Embedded I/O Configurations and Merging and I/O Configuration Techniques for detailed information.

Agilent VEE 8.5 adds support to Microsoft Office 2007 and Microsoft Excel 12.0 object library. Excel library provided by Agilent VEE works well in Agilent VEE 8.5 and has the same behaviors as before. In other words, existing programs developed using Agilent VEE Excel Library will work well with MS Office 2007 and MS Excel 12.0 object library.

Please note that existing programs, which directly write Excel automation code in a Formula, may have potential issues because some functions in previous Excel object library, like MS Excel 11.0 object library, may not be available in MS Excel 12.0 object library. Please refer to Microsoft website for more information on object model changes.

You can easily change the version of MATLAB to use in Default Preferences ( File => Default Preferences ) dialog box.

This feature allows users to set separate color for individual or group of Agilent VEE objects making Agilent VEE programs easier to read and code. It can also help users to tell which type an object belongs to just by its color. The following figure shows two programs. The above one is with Color Coding; the bottom one is the same program without Color Coding.

You can easily change, export or import color coding theme in Default Preferences (File => Default Preferences)dialog box.

See To Use Color Coding for more information.

See Uncertain Data Flow Compiler Warning for more information.

Four ways to create an I/O object for an instrument in the Instrument Manager:

  1. Double click an instrument in the instrument list to directly create an Direct IO object.

  2. Drag and drop an instrument from the instrument list to the workspace (and then choose an I/O object to create in the pop-up menu if there are more than one type of I/O object can be created for this instrument.)

  3. Use the context menu. Right click an instrument in the instrument list to open the context menu.

  4. Use the toolbar button.

See Instrument Manager for more information.

IO Monitor is a standalone tool that lets you:

  • Trace the API call stack of an Agilent IO Library.

  • Enable and disable the viewing of selected Agilent IO library layers.

  • Filter the reported data to control what you see.

  • Log trace information to a file for later review.

For more information on Agilent IO Monitor, refer to the online help of Agilent IO Monitor.

The Function & Object Browser is a tool window with convenient toolbar buttons and context menus.

Four ways to create a formula object for a selected item in the FOB:

  1. Double click an item in the member pane to directly create an formula object.

  2. Drag and drop an item from the member pane to the workspace (and then choose a formula object to create in the pop-up menu if there are more than one type of formula object can be created for this item.)

  3. Use the context menu. Right click an item in the member pane to open the context menu.

  4. Use the toolbar button.

See Function & Object Browser for more information.

Double clicking on a warning or error in the Output window can locate the object that causes the warning or error in the workspace.

See Output Window for more information.

This feature allows users to dynamically change an instrument's VISA Address among GPIB, USB, and TCP/IP interfaces. Users can also dynamically change an instrument's VISA Address within the same interface.

This feature can reduce instrument finding and configuration as well as the program complexity dramatically because users can dynamically change the instrument that they want to talk to without adding and configuring that instrument in the Instrument Manager in advance. Theoretically, if users want to use more than one GPIB, USB, or TCP/IP instrument to do the same test, they only need to add one of those instruments in the Instrument Manager, then they can talk to any GPIB, USB, or TCP/IP instruments connected as long as they know the VISA address of those instruments. Please see To Change VISA Interface and Address Dynamically for more information on how to use this new feature.

Please note that this feature is only for GPIB, USB, and TCP/IP instruments, not including other instruments connected via ASRL, legacy GPIB, etc.

Make sure that the VISA address is the correct physical address of the instrument you want to communicate with, or communication problems may occur.

Example: DynamicChangeVisaAdress.vee

This new feature allows users to integrate the Main UserObject into other commercial and proprietary test systems written in other languages, such as C/C++, VB, C#, script and macro in Microsoft Office (VBA). Users can now get whole control of Agilent VEE programs including Main and UserFunctions through Callable Server . See The Callable VEE ActiveX Automation Server for more details.

See File Open Dialog Box for more information.

Agilent VEE 8.5 introduces a new data type UInt16 and new execution mode VEE 8.5 for backward compatibility. See Execution Mode Changes: VEE 8 to VEE 8.5 for more information.

See UInt16 for more information.

New menu items and built-in functions added for UInt16:

  • Data => Constant => UInt16

  • Data => Constant => UInt16 Array

  • Data => Alloc Array => UInt16

  • asUInt16(x)

Agilent VEE 8.5 introduces a new data type UInt16 and new execution mode VEE 8.5 for backward compatibility. See Execution Mode Changes: VEE 8 to VEE 8.5 for more information.

See UInt16 for more information.

New menu items and built-in functions added for UInt16:

  • Data => Constant => UInt16

  • Data => Constant => UInt16 Array

  • Data => Alloc Array => UInt16

  • asUInt16(x)

Agilent VEE Pro 8.5 New Features

Modern Integrated Development Environment (MIDE) -- The Integrated Development Environment in version 8.5 gives the user a more modern and streamlined programming experience. This feature provides the user with additional functionalities and flexibilities including the ability to customize the development environment to better meet their needs. With version 8.5, you can dock, float, hide, move all your tool windows, such as Instrument Manager, Function & Object Browser, Program Explorer, Properties window, Watch window, Output window, Minimap, Call Stack, Profiler, etc.

Microsoft Windows Vista Support -- With Agilent VEE 8.5, you can take advantage of the latest Microsoft Operating System that is more secure and easier to use. The Windows Aero interface, the Windows Instant Search, and the Windows Sidebar bring you a new Microsoft Windows experience. The User Account Control (UAC) as well as other security related features will help maintain the health and security of your PC.

Per User Per Version VEE Configuration Files -- Starting from version 8.5, Agilent VEE saves configuration files with a per-user and per-version style, to eliminate problems caused by configuration differences between versions and users.

Microsoft Office 2007 Support -- Agilent VEE 8.5 supports Microsoft Office 2007 including the updated built-in Excel menu.

MATLAB 2007a Support -- Agilent VEE Pro 8.5 upgrades the MATLAB support to MATLAB 2007a. The number of supported MATLAB functions increases to 1800 with more than 1000 frequently used functions showing in FOB. Furthermore, you can easily choose the MATLAB version to use under the MATLAB tab in the Default Preferences dialog.

Color Coding -- This feature makes Agilent VEE programs easier to read by coloring different types of objects with different colors automatically. Users can also color objects as they need and export/import the color theme to share with others.

Uncertain Data Flow Compiler Warning -- Agilent VEE 8.5 gives a warning when potential compiler problem is found in an Agilent VEE program. More information on the compiler warning is also provided in Agilent VEE online help.

Graphical Display Objects Enhancement -- In Agilent VEE 8.5, all graphical display objects, such as XY trace, Strip Chart, etc., can display up to 255 traces.

Instrument Manager -- The Instrument Manager in version 8.5 is not only a tool window with brand-new UI which can dock, auto hide, or float, but it also provides more convenient features, including context menu and toolbar, to find, add, remove, and configure instruments and to create I/O objects quickly. In the Instrument Manager, you can now double click an instrument or drag and drop an instrument to the workspace to create an I/O object.

Using Agilent IO Monitor to Monitor Instant Communications -- Agilent VEE 8.5 replaces the old Bus I/O Monitor object with the Agilent IO Monitor, which is more powerful and easier to use.

Function & Object Browser (FOB) -- The newly designed Function & Object Browser allows you to easily browse and select functions and objects available for use in your program. You can even double click or drag and drop an item in the member pane ( the top-right pane) to quickly create an appropriate Formula object.

Output Window -- This feature helps you to debug your programs by logging Warning and Error messages during both run time and design time.

Dynamically Change VISA Interface and Address -- With version 8.5, by changing the VISA interface and address programmatically, you can communicate with the same instrument via different interfaces and addresses without extra configuration or coding.

Exposing Main from Callable Server -- Users can now call the Main UserObject from programs written in other languages such as C#, Visual Basic, C++, Excel Macro, and etc through the Callable Server interface.

M icrosoft Standard File Open Dialog -- In Agilent VEE 8.5, the old file open dialog box, which appears when you use the To/From File, To/From Dataset, or Import Library objects, is replaced by the standard Windows file open dialog box.

New Execution Mode and New Data Type -- Beginning with version 8.5, Agilent VEE supports a new data type - UInt16 and new Execution Mode - VEE 8.5.

VISA Change for ViReal32 -- Agilent VEE 8.5 supports ViReal32, ViReal32 [], and pViReal32 according to the latest VISA specification.

See Also

New Features and Enhancements in Past VEE Versions


Installing Agilent VEE

To Install Agilent VEE

Installing Agilent VEE and I/O Libraries

You can download or order an evaluation version of VEE. It is a fully functional version of the product. When you install it, you are prompted for a product key, enter “eval" without the quotes.

You can fully activate the evaluation version by purchasing a product key. Once you have received the product key in the mail, enter it from the main menu Help [image] Product Key. The full product can also be ordered or downloaded. A product key certificate is shipped to you with the product or separately if you have downloaded from the WWW.

VEE runs on the following Operating Systems: Windows 2000 SP4 or later, Windows XP SP2 or later and Windows Vista or later.

  • To install VEE from a CD-ROM. Be sure you are logged in as a user with administrative rights. Place the CD-ROM in your CD-ROM drive. The installation should start automatically. If it does not, go to the Start menu and choose Run. Enter

[CD-ROM drive letter]:\setup.exe

  • To install VEE from a WWW download. Download the VEE self-extracting executable. The downloaded, self-extracting file is located in the download directory of your choice. Extract the VEE installation files by running the self-extracting executable. The files are extracted into the directory of your choice. From this directory, run setup.exe.

To aid you with your security needs, you are prompted to install it for all users of the PC or for only one user. Choose whichever option fits your security needs.

For information about the I/O Libraries, refer to the installation materials you received with it. (The I/O Libraries are used by VEE to communicate with instruments.)

Installing and Distributing VEE Pro RunTime (Help [image] Contents and Index [image] Installing and Distributing VEE Pro RunTime) shows how to install and distribute the RunTime version of VEE Pro. The RunTime version is used to run VEE programs on PCs that do not have the VEE software installed. For more information about the runtime environment, refer to online Help. Select Help, Contents and Index, and Installing and Distributing Agilent VEE Pro RunTime.

See Also

Configuring VEE for Windows


Configuring VEE for Windows

To Configure Agilent VEE

You can change many VEE window properties in the VEE Default Preferences dialog box (use File [image] Default Preferences). These properties are saved in the default file VEE.RC and user.config in a default location. You can also customize the layout of tool windows and toolbars, the layout information is also saved in the same default location.

The default location for configuration files is

%Appdata%\Agilent\ProductName\MajorVersionNumber + ".” + FirstDigitofProductMinorNumber

-- %Appdata% is got from Environment.SpecialFolder.ApplicationData.

-- ProductName is the version name of Agilent VEE, such as, VEE Pro, VEE Runtime, VEE Express, etc.

-- ProductMajorNumber is the integer part of a product number. For example, for VEE 8.0, 8 is the product major number.

-- FirstDigitofProductMinorNumber is the first digit of the product minor number. Product minor number is the fractional part of a product number. For example, for VEE8.51, 51 is the product minor number, and its first digit is 5.

For example, the default location of VEE Pro 8.5 in Windows XP / 2K / Vista is %Appdata%\Agilent\VEE Pro\8.5.

The above default location is a per-user and per-version directory. Each user has separate configuration files for every version of Agilent VEE that is used. For example, if you are using both Agilent VEE Pro 8.5 and Agilent VEE Runtime 8.5, then there will be two sets of configuration files.

Color and Font Settings

You can save colors and fonts with the program by choosing File Þ Save As.

For colors and fonts, only the settings you change are saved in the VEE.RC default file.

Customizing Icon Bitmaps

You can change the icon displayed for any iconized object to a bitmap or pixmap. VEE provides many files, or you can create your own. VEE for Windows supports 24-bit .BMP bitmap files, .GIF87, .GIF89a, .PNG (Portable Network Graphics), and .WMF (Windows Meta Files). To select an object's icon, double click the object to bring up the Properties window, then use the Icon Appearance tab in the Properties window.

You can create your own bitmaps for object icons using any editor that outputs graphics formats that VEE supports, such as MS Windows Paint. You should specify 48x48 as the size for an icon. Larger icons use more space in the VEE program area while smaller icons are difficult to see. You can also use screen capture utilities such as Print Screen with Paint.

Selecting a Bitmap for a Panel View

You can select a bitmap to use as the background icon for a panel view. This applies to UserObjects and to VEE programs displayed in their panel views. Panel view icons must use the formats VEE supports. You can also use icons you create, as described in the previous paragraph.

To select a bitmap as the icon for a panel view, enable the panel view so the Panel and Detail buttons appear in the title bar (by adding an object to the panel). Open Properties window, then use the PanelBackgroundPicture item to choose a bitmap.

See Also

To Change Default Colors, To Change Default Fonts, I/O Configuration Techniques.


Using VEE Example Programs

To Use VEE Example Programs

VEE includes many example programs to help you understand how it works. The example programs are installed as part of the VEE installation process.

The Example Directories

The default directory for examples is:

C:\Program Files\Agilent\VEE Pro 8.0\examples\

Running the Examples

You can load and run example programs using the Help menu, as follows:

1 Click Help Þ Open Example on the menu bar. This presents a list of subdirectories that group similar examples together. (You can also use File Þ Open Þ Examples to load VEE examples.)

2 Double-click the desired subdirectory to see the programs in that group.

3 Scroll through the list until you find the desired example.

4 Click the example name, then click OK to open the program. You are prompted to save the any existing program in the work area.

5 To run the program, press the Run button on the tool bar.


To Start Agilent VEE for Windows

To Start Agilent VEE

You can start multiple copies of VEE running on the same PC. However, if two copies of VEE attempt to access the same system resource (for example, an I/O interface) at the same time, unexpected results may occur.

For information about using VEE Pro RunTime to run programs, see Preventing Program Changes and To Create an Application Icon in Windows.

Using the Windows Start Button

1. Click the Start button, and then point to Programs [image] Agilent VEE Pro 8.0.

Starting from the Windows Desktop

1. Follow the directions in Windows Help to put a shortcut for the Agilent VEE application file on the desktop using Windows Explorer.

By default, VEE is installed in:

C:\Program Files\Agilent\VEE Pro 8.0\vee.exe

unless you installed it in another directory.

2. Once the shortcut is in place, double-click on the shortcut icon to start Agilent VEE.

See Also

To Start Agilent VEE with Command Line Options


To Start Agilent VEE with Command-Line Options

Agilent VEE provides several command-line options that you can use to start VEE and VEE Pro RunTime. For example, you can specify a VEE program file to load when VEE starts. Also, you can choose to load and run a program in VEE Pro RunTime.

To start VEE and VEE Pro RunTime using the command-line options

1. Click on the Windows Start button, and then click on Run...

2. Type vee or veerun, followed by the desired option(s), and press Enter. The veerun command also requires a program file name after the option(s).

or

1. Open an MS-DOS window.

2. Type start vee.exe or start veerun.exe, followed by the desired option(s), and press Enter. The veerun command also requires a program file name after the option(s).

Scroll down through this topic for available options and examples.

Tip

If you put a shortcut for VEE on the desktop, you can modify the shortcut’s properties to include command-line options.

Scroll down through this topic for available options and examples.

Available Options

The following table shows the options available for each platform when using VEE or VEE Pro RunTime. A description of each option appears below the table.

Option | Windows
 | VEE | VEE Runtime
--custom_option | X | X
-d directory | X | X
-disallowclose |  | X
-enablewarnings |  | X
filename | X | X
-geometry | X | X
-help | X | X
-iconic | X | X
-ioconfig |  | X
-maximize | X | X
-noerrdisp | X |
-nologo | X |
-prefconfig |  | X
-r filename | X |
-secure ProgramName | X |
-stderr:filename ProgramName | X | X
-stdout:filename ProgramName | X | X
-veeio path to filename | X | X

Option Descriptions

--custom_option

The custom_option will be passed through to the VEE program. The users can use the built-in function commandLIne() to retrieve the options. See commandLine() for detailed information.

-d directory

The -d option starts VEE and uses the related files, such as instrument drivers, located in the specified directory instead of the default VEE installation directory.

-disallowclose

Prevents the user from closing the VEE Pro RunTime window while a program is running.

-enablewarnings

Enables the display of error and caution dialog boxes when loading a program into VEE Pro RunTime. Without this option, VEE Pro RunTime suppresses all normal error and caution dialogs during program loading. With normal error displays disabled, a failed load gives only a generic (less useful) message, such as: "File format is invalid." With
-enablewarnings, you can see a more specific cause of the problem.

filename

This is optional for the vee command, and required for the veerun command. The vee command starts VEE and opens the VEE program specified by filename in the VEE work area. The veerun command starts VEE Pro RunTime and runs the VEE program specified by filename. For Windows, if filename contains spaces, then the entire file name, including the path, must include quotation marks.

-geometry widthXheight+/-xoffset+/-yoffset
or
-geometry +/-xoffset+/-yoffset (to use default window size)

Specifies an initial window geometry to be used instead of the default geometry. Geometry values are in pixels. Positive offset values position the top-left corner of the window relative to the top-left corner of the screen. Negative offset values position the bottom-right corner of the window relative to the bottom-right corner of the screen.

The offset +0+0 is the top-left corner of your screen.

Example: -geometry 640X480+20+20 starts VEE in a window that is 640 pixels wide and 480 pixels high, that is placed 20 pixels to the right and 20 pixels down from the top-left corner of the screen.

-help

Shows the VEE command line options. (Not to be confused with the VEE online help system, which is launched from within VEE.)

-iconic

The -iconic option starts VEE as an icon instead of a window. Double-click on the icon to open it to a window.

-ioconfig

This option opens the Instrument Manager dialog box in the VEE Pro RunTime window allowing changes to the I/O configuration file vee.io. Do not include a program file name with this command; it is ignored.

If the Instrument Manager dialog does not fit within the VEE window, you can make the VEE or VEERun window larger by also using the -geometry option.

-maximize

This option starts VEE in an enlarged window that fills the screen.

-noerrdisp

This option can be used in conjunction with -r. If used with -r, and the specified program does not run due to an error, VEE exits immediately without displaying an error message.

-nologo

This option suppresses the startup information that appears before VEE starts running. On Windows, the startup information box does not appear.

-prefconfig

This option opens the Default Preferences dialog box in the VEE Pro RunTime window allowing changes to the default configuration. Do not include a program file name with this command; it is ignored.

If the Default Preferences dialog does not fit within the VEE window, you can make the VEE or VEERun window larger by also using the -geometry option.

-r filename

The -r option starts VEE and runs the VEE program specified by filename. When the program finishes running, VEE exits immediately. However, if an error occurs, an error message is displayed before VEE exits. If you do not specify a file name, VEE ignores the -r option. If filename contains spaces, then the entire file name, including the path, must be quoted. Generally, the veerun command is better to use than the -r option.

-secure ProgramName

Creates a secured program using ProgramName as the source file. The following command creates the file myProg.vxe in the same directory as the source file:

vee -secure myProg

-stderr:filename ProgramName

Creates a standard error log file named filename, and logs error information generated by VEE (if errors occur) while loading and running ProgramName. You can include a directory path with filename.

-stdout:filename ProgramName

Creates a standard output file named filename, and logs information generated by VEE (if any occur) while loading and running ProgramName. You can include a directory path with filename.

-veeio path to filename

VEE lets you have multiple I/O configuration files (vee.io). This option lets you specify the one you want to use when you start VEE.

Example: Starting VEE for Windows Using filename

To start Agilent VEE for Windows and automatically open the program myprog.vee:

1. Click on the Windows Start button, and then click on Run...

2. Type vee myprog.vee and press Enter. Surround file names with quotation marks if they contain spaces.

or

1. Open an MS-DOS window.

2. Type start vee myprog.vee and press Enter. Specify a path if the program is not in the current directory. Surround file names with quotation marks if they contain spaces.

Example: Starting VEE RunTime for Windows using -disallowclose

To run the program myprog.vee in VEE RunTime for Windows and prevent closure of the execution window:

1. Click on the Windows Start button, and then click on Run...

2. Type veerun -disallowclose myprog and press Enter. Surround file names with quotation marks if they contain spaces.

or

1. Open an MS-DOS window.

2. Type start veerun -disallowclose myprog and press Enter. Specify a path if the program is not in the current directory. Surround file names with quotation marks if they contain spaces.

See Also

To Create an Application Icon in Windows, To Start Agilent VEE


Interacting with Agilent VEE

This section explains how to use the VEE graphical programming language, including a list of systems supported, how the mouse and menus work, how to get help, and how to work in the VEE window.

Supported Systems

This version of VEE is supported on the following operating systems:

  • Windows Vista (32-bit only, Business, Ultimate, and Enterprise) or higher, Windows 2000 SP4 or higher, Windows XP SP2 or higher.

It requires the following additional software if you need to communicate with instruments using Agilent VEE:

  • Agilent IO Libraries Suite 15.0 or higher and/or NI Libraries version 3.0.

The Mouse and the Menus

You are probably familiar with the computer’s mouse- and menu-driven interface: the pull-down menus, toolbars, and dialog boxes that you control with the mouse and keyboard. VEE uses your computer’s interface. In the instructions about using the mouse to operate menus, icons, buttons, and objects, the common techniques are as follows:

  • To “click” an item, place the mouse pointer on the desired item and quickly press and release the left mouse button.

  • To “double-click” an item, place the mouse pointer on the desired item and click the left mouse button twice, in rapid succession.

  • To “drag” an item, place the mouse pointer on a desired item, hold the left mouse button down, and move the item to the appropriate location. Then, release the mouse button.

Note

The right mouse button is used less frequently. You are advised if you need to click the right mouse button. If your mouse has a middle button, you will not use it for VEE.

The Agilent VEE Window

After you have installed and started VEE, you will see the VEE window shown as following figure.

These items describe the parts of the VEE window.

Screen Descriptors | Description
Title bar | The top line in the window contains the VEE icon, the window name, and the minimize, maximize, and close buttons. Move the window by dragging the title bar. Click the VEE icon to get the window’s menu.
Menu bar | The second line contains menu items, each of which provides VEE commands or objects.
Toolbar | The third line contains icons, or buttons, that provide direct access (or “shortcuts”) to the most commonly used menu commands. (Place the mouse pointer over a button and VEE displays its function.)
Work area | A region in a programming (edit) window such as Main, UserObject, or UserFunction where you place objects and wire them together.
Program Explorer | A tool window that shows the structure of the VEE program. The upper corner shows the current program name, such as myprog.vee, or it displays Untitled. The Program Explorer lets you move among the programming windows.
Properties Window | A tool window that shows the properties of VEE objects. To edit properties of an object, click the object in work area first, then click the value field of the property to edit in the Properties window,and then edit it.
Output window | A tool window that contains Warning and Error messages.
Status bar | The bottom line displays messages about VEE status, including four status indicators in the right corner. The indicators (from left to right) show: The execution mode The state of the profiler MOD appears when the program has been modified Web server is enabled.

Getting Help

VEE provides an online Help system for the VEE environment, and online Help for individual objects and topics. In addition, you can get help in the documentation that came with the computer and its operating system. The PC online Help includes information about topics such as:

  • Choosing commands on the menu bar

  • Selecting and dismissing menu items

  • Using toolbars

  • Understanding title bars and status bars

  • Clicking icons and buttons

  • Working with dialog boxes

  • Working with various types of windows

  • Using online help

To begin, you may want to start with the Help [image] Welcome screen, where you can access the VEE Multimedia Tutorials. The Welcome screen is shown below.

VEE online Help is designed for your operating system. Click Help and the following menu appears. Help includes contents and index, the Welcome menu (where the Tutorials are located), instrument drivers, Web site information, examples, and version number.

Although you do not need to use VEE documentation to complete this self-paced training, consult the product documentation for more detailed information about any particular feature or concept. Use the Help system to search for VEE topics you need to locate. The Help system can “jump” to related topics.

Select Contents and Index to start VEE Help.

The Help Contents tab contains the following topics.

What’s New in VEE | Definition
How Do I... | Provides “how to” information for common tasks.
Tell Me About... | Explains VEE concepts.
Guide to Agilent VEE Example Programs | Summarizes example programs shipped with VEE.
Reference | Provides reference information for all functions and objects.
About Agilent VEE Support | Provides information about getting support for VEE.
Installing and Distributing Agilent VEE Pro Runtime | Explains how to distribute the VEE Pro RunTime environment.

Note

As a shortcut to get help on a selected object and on dialog boxes, press F1 on your keyboard. In addition, Click Help in an object menu to get specific information about that object.

For more information about using specific online Help features as you develop programs, refer to Using Online Help

Copyright (c) 1991-2007 Agilent Technologies, Inc.


Working with Objects

To Work with Objects

A VEE program consists of connected objects. To create a program, select objects from VEE menus, such as Flow, Data, and Display. Connect the objects via lines that attach to the object pins. (For more information about pins, refer to "Understanding Pins and Terminals"). Create a program with a group of connected objects.

This section describes how to select and use objects in a program.

1 Start VEE. Click Start [image] Programs [image] Agilent VEE Pro in Windows.

2 Follow the instructions in this section to experiment with objects.

Adding Objects to the Work Area

Pull down an appropriate menu, click the desired object, drag the object to an appropriate location in the work area, and click (the outline will disappear and the object will appear).

1 For example, to add a Function Generator object to the work area, select Device [image] Virtual Source [image] Function Generator in the menu bar as shown in following figure. An outline of the object appears in the work area.

note

The arrow to the right of Virtual Source indicates a submenu. Three dots after a menu item indicate that one or more dialog boxes will follow. For example, File [image] Save As... operates this way.

2 Move the Function Generator to the center of the work area, and click to place the object. The Function Generator appears.

Having placed an object in the work area, you can move the object by dragging its title bar, just as you move a window.

note

In this online help, a shorthand notation is used to explain instructions. For example, selecting the Function Generator object is condensed into the following format:
Device [image] Virtual Source [image] Function Generator

Changing Object Views

VEE displays objects either in “icon view” or “open view”.

Open View Icon View

The iconic view conserves space in the work area and makes programs more readable. The open view provides more detail and allows you to edit the properties and settings of an object.

1 To switch from an open to iconic view, click the Minimize button (the box on the right end of the object's title bar).

2 To return to an open view, double-click the object icon view (anywhere on the object).

Not all objects have the same structure or parts, but you can edit objects in their open views and save space in their icon views.

note

The object menu also has Minimize and Restore selections. To display the object menu, click on the Object Menu button on the left end of the title bar, or right click anywhere on the object.

Selecting an Object Menu

Each VEE object has an object menu that lets you perform actions on the object, such as Clone, Size, Move, and Minimize. Most objects have similar attributes, but there are differences, depending on the functionality of the object.

1 To select the object menu, click once on the object menu button. (All object menus open the same way.) The object menu appears, as follows. (Do not double-click the object menu button. That is the shortcut for deleting the object.)

2 Now you can click one of the object menu choices to perform the action you desire. Or, to dismiss the menu, click an empty area outside the menu.

You can also select the object menu by placing the mouse pointer anywhere on the object body and clicking the right mouse button. This works for both the open and icon views.

Moving an Object

1 To move the Function Generator object, click Move in the object menu, then click and hold the left mouse button. An outline of the object appears.

2 Move the outline to the new location while continuing to hold the mouse button down. Release the mouse button, and the object moves to the new location.

You can also move objects as follows:

• Click the title area of the open view of an object and drag the object to a new location.

• Except for buttons, entry fields, pins, terminals, or the four corners (which resize the object), click any part of an open view object and drag the object to a new location.

• Click any part of an icon view object except near the four corners (which resize the object), and drag the icon to a new location.

note

“Object Location Information, located on the status bar (at the bottom of the VEE window) gives the X and Y position (in pixels) of the upper-left corner of the outline relative to the upper-left corner of the workspace. To view an object’s exact location, left click on an object to select it and hold the left mouse button down. The location is displayed in the status bar. Use this information when you need to place an object in an exact position.

Duplicating (or Cloning) an Object

The Clone operation creates a duplicate object exactly, including any changes you have made such as sizing or renaming. Cloning is a shortcut for copying and pasting.

1 Open the object menu and select Clone. An outline of the duplicated object appears.

2 Move the outline to the desired location, and click to place the object. The cloned object appears, while the original object remains. In following figure the Function Generator has already been cloned once, and the object menu has the command selected to clone it again.

Copying an Object

This action copies an object to the clipboard, so you could Paste it to VEE or another application such as MS Paint or MS Word.

Click on an object to highlight it, then click Edit [image] Copy.

-OR-

Click on an object to highlight it, then press Ctrl-C.

Deleting an Object

To delete an object from the work area, go to the object menu for the object you want to delete and click Delete. For example, go to the object menu for the Function Generator and click Delete. The object disappears from the work area, but it is saved in the buffer.

Open the object menu, and select Delete.

-OR-

Select the object (click on it) and press Ctrl-X.

-OR-

Place the mouse cursor over the object menu and double-click.

note

Be careful. It is easy to accidentally delete an object by double-clicking its object menu button. If you do delete an object by accident, use the Undo toolbar button (or Edit [image] Undo) to recover the object and all connections to it.

Pasting an Object

To paste a copied object back into the work area, follow these steps.

After an object has been cloned, copied or deleted (using Ctrl-X ),

click Edit [image] Paste. An outline of the object appears. Place the object and click to release it.

-OR-

Press Ctrl-V.

Changing the Size of an Object

Place the mouse pointer over any of the four corners of the object until you see a sizing arrow, then click-and-drag to the desired size. Release to resize. This figure shows an object being resized with the sizing arrow.

-OR-

Open the object menu and click Size. The mouse pointer becomes a “bottom-right-corner” bracket. Move the bracket to the desired position of the lower-right corner and click to resize.

Changing the Name (Title) of an Object

1 Open the object menu and select Properties... A Properties window appears on the left side of your screen. Select the Title property and change the property value to whatever you would like.

2 The new title appears in the title area. If you minimize the object, the new title appears in the icon.

-OR-

Double-click the object title bar to go directly to the Properties dialog box.

note

You can save time by using standard keyboard and mouse editing techniques. For example, in the Properties dialog box Title field, if you click at the extreme left edge of the edit area the cursor will appear there. You can then add new text without deleting the existing title.

Selecting or Deselecting Objects

1 To select an object, click on the object and a shadow appears behind it. For example, in the following figure, the For Count object is selected.

2 To deselect an object, move the mouse pointer over any open area and click. The shadow disappears. For example, in the following figure, the Formula object is not selected.

note

The word “select” is also used to indicate choosing a menu item, but the context makes the meaning obvious.

Selecting Several Objects

If you click to select an object, only one object is selected. If you click again to select another object, the previous object is deselected and its shadow disappears. To select multiple objects when you want to perform an operation on all of them at once, such as Delete, follow these steps:

Press and hold down the Ctrl button as you click on different objects. Release the Ctrl button after you have highlighted all the objects you want to select.

-OR-

Press Ctrl, then click-and-drag a rectangle around the objects to be selected. The selected objects become shadowed.

Selecting/Deselecting All Objects

1 To select all objects, click Edit [image] Select All. (Or press Ctrl-A.)

2 To deselect all objects, click on an open area in the window.

Copying Multiple Objects

Copy the selected objects by placing the cursor on an object. Press and hold Ctrl while using the left mouse button to drag the multiple objects (outlines) to a desired location. A new instance of each object appears in the desired location.

-OR-

Or, use Edit [image] Copy to copy the selected objects to the buffer. Click Paste (in the Edit menu or on the toolbar), move the objects (outlines) to a desired location, and click the left mouse button. Following figure shows objects during copying.

note

In VEE, objects that you cut or copy are also placed on the Clipboard. You can paste them into other Windows applications that support the Windows Clipboard.

Editing Objects

There are several ways to edit objects in VEE. Different editing menus display different choices. Choose an editing menu or icon as follows:

Click Edit on the VEE menu bar to display the Edit menu, and select the operation you want. The commands in the Edit menu are the same for all of VEE.

-OR-

Click on an icon on the VEE toolbar. The VEE toolbar contains icons for frequently used editing commands such as Cut, Copy, and Paste.

-OR-

Open the object’s object menu by clicking on it, and select the operation you want. Object menus include editing operations specific to an object, such as the Properties menu, that are not located in the main Edit menu. The commands in the object menu also vary depending on the type of object. For example, compare the object menus for the Device [image] Formula and I/O [image] To [image] File objects. The two menus contain different choices that are specific to the object.

-OR-

Place the mouse pointer anywhere on a blank work area space and click the right mouse button. A pop-up Edit menu appears.

note

Inactive menu items appear in a different shade than active items (they are “grayed out”). For instance, the Cut, Copy, and Clone operations in the Edit menu appear in a different shade from active menu items until an object is highlighted in the work area

Creating Data Lines Between Objects

1 Click on or just outside the data output pin of one object, then click on the data input pin of another, as shown below (A line appears behind the pointer as you move from one pin to the other.)

2 Release the cursor and VEE draws a line between the two objects. Notice that if you reposition the objects, VEE maintains the line between them.

For more information on pins, see "Understanding Pins and Terminals".

Deleting Data Lines Between Objects

Press Shift-Ctrl and click the line you want to delete.

-OR-

Select Edit [image] Delete Line and click the line you want to delete.

Moving the Entire Work Area

(Make sure there is at least one icon in the work area.) Place the mouse pointer anywhere on the background of the work area, press and hold the left mouse button, and move the work area in any direction.

Scroll bars appear if your program is larger than the work area, as shown below.

note

If you click near a terminal, a line or “wire” may appear. If this happens, move the pointer to an open area and double-click.

Clearing the Work Area

Click Edit [image] Select All and then click the Cut button on the toolbar. This cuts all objects in the active window to the Cut buffer.

-OR-

Select File [image] New, or click the New button on the toolbar. VEE asks you if you want to save changes.

-OR-

Clear individual objects by clicking an object to make it active, and then clicking the Cut button on the toolbar.

Changing Default Preferences

The Default Preferences dialog box changes the default settings in the VEE environment.

Click the Default Preferences button on the toolbar.

-OR-

Click File [image] Default Preferences. The Default Preferences dialog box appears.

This dialog box has tabs that let you select options to edit.

Tab Name | Description
General | The default tab when the Default Preferences dialog box appears (shown previously). You can change the values of the displayed parameters; for example, Environment and Execution Mode.
Colors | Lets you customize the colors in the VEE environment.
Fonts | Lets you customize the fonts in the VEE environment.
Number | Lets you change the default number format.
Printing | Lets you set the values of the parameters for a printer.
Web Server | Lets you enable the built-in Web server to monitor and troubleshoot a program from a remote Web browser.

For more information, select Help [image] Contents and Index from the VEE menu bar. Then, browse How Do I..., Tell Me About..., or Reference.

See Also

How objects Operate, How Agilent VEE Programs Work

Copyright (c) 1991-2006 Agilent Technologies, Inc.


Understanding Pins and Terminals

A VEE program consists of the objects in the work area and the lines that connect them. The lines that connect VEE objects are connected between object pins. Each object has several pins. Here, the Formula object is used as an example. You can use any object.

Pin Type | .Description
Data Input Pin | The pin (or pins) on the left-hand side of an object.
Data Output Pin | The pin (or pins) on the right-hand side of an object.
Sequence Input Pin | The pin on the top of an object.
Sequence Output Pin | The pin on the bottom of an object.

Connect the data input and output pins to carry data between objects. By default, the pins execute from top to bottom. The sequence pin connections are optional. If connected, they will dictate an execution order.

For more information, refer to Following the Execution Order of Objects in a Program.

In an object’s open view, the data input and output pins appear as input and output terminals. (If the object is in icon view, double-click it to switch to open view.) The terminals carry detailed information such as the name of the terminal, and the type and value of the data being transmitted. The terminal labels are visible only in the open view, and only if the Show Terminals option is turned on for that object (see Properties... in the object’s menu).

For example, the following figure includes two Formula objects. The Formula object on the left shows the terminal labels A and Result. The Formula object on the right has Show Terminals turned off, and the labels are not visible.

Show terminals is turned on Show terminals is turned off

To turn Show Terminals ON or OFF, select Properties from the object menu. The properties window appears on the left side of your screen. Select the property ShowTerminals and set it to True.

Select the property and set ShowTerminals to False. Select the property again and set ShowTerminals to True.

Adding a Terminal

You can add terminals to an object. For example, you can add a second data input terminal to the Formula object.

Open the object menu and select Add Terminal [image] Data Input.

-OR-

With Show Terminals turned on, you can place the mouse pointer in the “terminal area” (the left margin of the open view object) and press Ctrl+A (press the Ctrl and A keys simultaneously).

Following figure shows the Formula object menu open to add a data input terminal, and another Formula object that has a second terminal already added. The new terminal is labeled B. If the data inputs are tied to particular functions, as with instrument drivers, you are given a menu of these functions. Otherwise, the terminals are named A, B, C... .

Editing Terminal Information

To obtain information about a terminal, double-click the label area. For example, double-clicking B causes the dialog box to appear.

You can now edit the terminal. The dialog box has three kinds of fields:

Field Type | Description
Entry field | A field with a white background, but no arrow. It becomes a type-in field when you click it. For example, you can click B in the Name field and rename the terminal.
Status field | A field with a gray background that cannot be edited. For example, the Mode field cannot be edited.
Selection field | A field with a white background that has an arrow on its right-hand side. Clicking the field or its arrow displays a drop-down list. For example, if you click Any (or the arrow) in the Required Type field, you can select another data type from the list by clicking the list as shown follows.

If you select a data type other than Any for a data input terminal, only the specified type of data or data that can be converted to that type will be accepted by the terminal. Most of the time it is best to leave the Required Type and Required Shape fields set to Any. For more information, select Help [image] Contents and Index from the VEE menu bar. Then, browse How Do I..., Tell Me About..., or Reference.

Deleting a Terminal

Open the object menu and select Delete Terminal [image] Input... or Delete Terminal [image] Output, choose the input or output to delete, and click OK. For example, following figure shows the dialog box that appears when you choose Delete Terminal [image] Input....

-OR-

Place the mouse pointer over the terminal and press CTRL-D.

If you decide you did not want to delete the terminal, select the Undo button from the Taskbar.

See Also

Connecting Objects to Make a Program


Finding the Menu Location for an Object

To Find the Menu Location for an Object

To find the location for an object in the menus, and to display the information about that object, select Help => Contents and Index, click on the Index tab, type in the name of the object, and click Display.

For example, select Help => Contents and Index, click on the Index tab, and type in Collector. Click Display to display the Help topic for the Collector object.


To Customize Toolbar

To Customize the VEE Toolbars

You can create or remove a toolbar, change the layout, position, and content of the toolbar in the Agilent VEE integrated development environment (IDE). You can also add or remove buttons to or from the toolbar and change the display style for any button.

To Create New Toolbars

To create a new toolbar

1. Right click on a toolbar or on the VEE menu bar, open the Tools menu.

2. On the Tools menu, choose Customize....

3. In the Customize dialog box, select the Toolbars tab.

4. Choose New.

5. In the New Toolbar dialog box, type a name for the toolbar.

6. Choose OK.

To add a command button to a toolbar

1. Right click on a toolbar or on the VEE menu bar, open the Tools menu.

2. On the Tools menu, choose Customize....

3. In the Customize dialog box, select the Commands tab.

4. Select category and drag the command out of this dialog box to a toolbar.

To Customize Toolbar Buttons

You can change many properties of toolbar buttons, like name, image, display style, etc.

To customize toolbar buttons

1. Right click on a toolbar or on the VEE menu bar, open the Tools menu.

2. On the Tools menu, choose Customize....

3. In the Customize dialog box, select the Commands tab.

4. Select a toolbar button which you intend to customize in a toolbar.

5. Click Modify Selection button under the Command tab in the Customize dialog box to open a menu list.

6. Choose the command you want in the list.

Please note that you can remove a button from a toolbar by choosing the Delete in the list.

Note

The Customize dialog box can be used to customize menus as well. The process is the same as to customize a toolbar button, the only difference is you need to select a menu item instead of a toolbar button in step 4.

To Add or Remove a Toolbar

1. Right click on a toolbar or on the VEE menu bar, open the Tools menu.

2. Check or uncheck a toolbar to add or remove it.

See Also

To Customize Agilent VEE Menu, To Arrange and Dock Tool Windows


To Customize the VEE Menus

You can customize the menus in the VEE development environment. The file customMenu.mnu explains how to add items to the menus for special objects and functions you want to use frequently. It also explains how to use the new built-in function help() to add links to custom Help topics for programs you develop.

The file customMenu.mnu is located under the VEE installation directory, in lib. You can open it in an ASCII text editor.

See also

help(), To Customize the VEE Toolbars, To Arrange and Dock Tool Windows


To Arrange and Dock Tool Windows

You have many options for arranging tool windows within the IDE, including the following:

  • Dock tool windows to the edge of a frame in the IDE.

  • Hide tool windows along the edge of the IDE.

  • Reset window placement to the default layout.

In Agilent VEE tool windows includes Function & Object Browser window, Instrument Manager window, Program Explorer window, Properties window, Output window, Minimap window, Watch window, Call Stack, and Profiler.

To Dock Tool Windows

When a tool window is dockable, it can be fastened to one side of a frame within the IDE. A guide diamond appears when you drag tool windows from their current location to another location in the IDE. See the following figure. The four blue rectangles rounded by the red square is the guide diamond.

The guide diamond allows you to quickly re-dock a tool window on one of the four sides of the IDE. When a tool window is undocked or not dockable, it floats on top of the other windows. You can move tool windows outside of Agilent VEE workspace when they float.

To dock tool windows

Click the tool window you want to dock, to give it focus.

Right click the title bar of the tool window, open its Window Menu.

On the Window menu, click Dockable.

Drag the tool window from its current location towards the middle of the IDE.

A guide diamond appears. The four arrows of the diamond point towards the four edges of the IDE.

When the window you are dragging reaches the position where you want to dock it, move the pointer over the corresponding portion of the guide diamond. An outline of the window appears in the designated area.

To dock the window in the position indicated, release the mouse button.

For example, if Program Explorer is docked on the right edge of the IDE and you want to dock it on the left edge, you would drag Program Explorer towards the middle of the IDE, move the pointer over the left side of the guide diamond, and then release the mouse button.

Tip

To move a dockable window without snapping it into place, press CTRL while dragging it.

To Hide Tool Windows

Tool windows support a feature called Auto Hide. Auto Hide enables you to see more of your code at one time by minimizing tool windows along the edges of the IDE when not in use.

To turn on Auto Hide

Click the window you want to hide to give it focus.

Right click the title bar of the tool window, open its Window Menu.

On the Window menu, click Auto-Hide.

— or —

Click the pushpin icon [image] on the title bar of the window.

When an auto-hidden window loses focus, it automatically slides back to its tab on the edge of the IDE. While a window is auto-hidden, its name and icon are visible on a tab at the edge of the IDE. To display an auto-hidden window, move your pointer over the tab. The window slides back into view and is ready for use.

To turn off Auto Hide

Click the window you want to keep visible to give it focus.

Right click the title bar of the tool window, open its Window Menu.

On the Window menu, click Hide or Dockable.

— or —

Click the pushpin icon [image] on the title bar of the window.

Tip

Tool windows that have Auto Hide enabled temporarily slide into view when the window has focus. To hide the window again, select an item outside of the current window. Once the window loses focus, it slides back out of view.

To Reset Tool Window Layouts

You can return the IDE to the VEE default factory IDE layout using the Window => Reset Tool Bar / Window Layout command. When you run this command, the following actions occur:

  • All toolbars and windows are moved to their default positions.

  • Toolbars and windows that are closed in the default IDE layout are closed by the command.

  • Toolbars and windows that are open in the default IDE layout are opened by the command.

To Save / Load User Tool Bar / Window Layout

You can save the current IDE layout using the Window => Save Tool Bar / Window Layout command, or load the saved IDE layout using the Window => Load Tool Bar / Window Layout command.

See Also

To Customize the VEE Menus, To Customize the VEE Toolbars


To Open a VEE Example File

To Open an Example Program File

Tip

The following topic in VEE Help contains descriptions of the example programs and links that load them into a new VEE window:

Guide to VEE Example Programs

Agilent VEE

Several example programs are provided with VEE. These examples are found in subdirectories under
C:\Program Files\Agilent\VEE Pro 8.0\examples.
For instance, the examples for using MATLAB Script in VEE are found in the subdirectory:

C:\Program Files\Agilent\VEE Pro 8.5\examples\MATLAB

You can open any program file, including an example, by clicking on the Open button on the VEE toolbar. However, for your convenience you can open an example program file from Help:

1. Select Help [image] Open Example. The Open File dialog box appears, but is "targeted" on the examples directory.

2. Double-click a subdirectory name.

3. Click on the file name of the example file you want to open, then click on Open.


To Open a VEE Program File

1. Click the Open button on the VEE toolbar. The Open File dialog box appears.

The Open File dialog box looks for program files to open in the default directory
C:\Documents and Settings\[your username]\My Documents\VEE Programs.
(By default, clicking the Save button saves your programs in that directory.)

Open button

Save button

2. Click on the file name of the program file that you want to open, and then click on Open. Or enter the name of a file in the File name type-in field and click on Open.


To Merge Objects and Programs from Library Files

VEE provides several library objects (pre-built UserObjects) and complete library programs that you can merge into your own VEE program.

1. Select File [image] Merge. The Merge dialog box appears.

By default, the Merge dialog box looks for library objects and programs in the directory
C:\Program Files\Agilent\VEE Pro 8.0\lib.
You can also merge any VEE program file into the work area by changing directories.

2. Click on the file name of the library file that you want to open, and then click on Open. The object is merged into your workspace. You can connect it into your program like any VEE object.


To Start a VEE Program

Agilent VEE provides several execution modes for running programs. They are VEE 3, VEE 4, VEE 5, VEE 6 and VEE 8. You set the mode using Default Preferences. Programs written with VEE 8.0 will, by default, run in VEE 8 execution mode. Programs written with VEE 7.X or VEE 6.0 will, by default, run in VEE 6 execution mode. Programs written with VEE 5.0 will, by default, run in VEE 5 execution mode. Programs written with VEE 4.x will, by default, run in VEE 4 execution mode, and older programs will run in VEE 3 execution mode. You can run older programs in newer modes, but they may not run as expected, and may need revision. VEE 3-mode programs should be revised as needed to run properly in VEE 4 mode before running them in VEE 5 or higher modes.

To start an entire VEE program, including all threads within the program, click the Run button on the VEE toolbar.

Run button

All threads within the work area will start, whether or not they have a Start object.

If you want to be able to start an individual thread in a program independently, add a Start object (under the Flow menu) to the thread. When you click on a Start object button, only the thread that contains the Start object will start.

If a thread employs feedback, the thread must contain a Junction object inside the feedback cycle to run in VEE 4 or higher execution modes. This is the only case where a Junction object is required. If you run a program that includes a thread with feedback, but no Junction object, an error is reported.

Example: Two threads, each with a Start object

If you want to run just the top thread, click on its Start button. The thread runs, displaying "Now is the time" in the AlphaNumeric object, as shown. However, the bottom thread does not run.

If you click on Start in the bottom thread, it runs, but the top thread does not.

If you click on the Run button, both threads of the program will run. In each thread, propagation begins at the Start object.

Shortcuts

Press CTRL+G on the keyboard to run a VEE program.

See also

Default Preferences


To Branch within a VEE Program

To branch the flow of execution within a VEE program, use the If/Then/Else or Conditional [image] objects found under the Flow menu.

To set up a conditional branch using the If/Then/Else object

1. Add an If/Then/Else object (from the Flow menu) to the work area.

2. Modify the conditional test expression as desired. For example, to test values to see if they are in the range "greater than or equal to 0.5 and less than 0.6", use the expression .5<=A AND A<.6. (You can use any of the logical or relational math operators supported by VEE in the expression field of an If/Then/Else object, as call UserFunctions and access global variables.)

3. Add additional data input terminals if required by your new expression. By default, there is only one data input terminal (A). If you want to test a value A against a value B (for example, A<=B), add a data input terminal named B.

4. Connect the sources of data to be tested to the data input terminals.

5. Finally, connect the Then and Else output terminals to activate different objects or subthreads in your program, as desired.

Example: Using If/Then/Else

The value output by the Random Number object is tested against the expression .5<=A AND A<.6. If the value is in the specified range, the Then output terminal activates the top AlphaNumeric object, which displays the random number as shown in the above figure. If the value is not in the specified range, the Else output terminal activates the bottom AlphaNumeric object, which displays Try Again. This example illustrates a simple case; you can use the Then and Else terminals to activate any sort of program thread. This example is saved as manual01.vee in your manual examples directory (Help [image] Open Example)

To Use the Conditional Objects

The objects under Flow [image] Conditional [image] (If A == B, If A ~= B, If A != B, If A < B, If A > B, If A <= B, and If A >= B) are really pre-defined If/Then/Else objects. Each has two data input terminals (A and B) and performs a pre-defined test comparing the value of A to the value of B. The Then and Else output terminals work just as in the If/Then/Else object. In fact, you can add or delete terminals and change the expression just as you would in an If/Then/Else object. For example, you could add a C terminal to the If A == B object and change the test to A == B OR B <= C.

Example: Adding Else If Conditions

The If/Then/Else and Conditional objects have another feature -- the Else If condition. You can add one or more Else If conditions (object menu [image] Add Else/If). Each Else If condition is tested if the previous condition is not met. For example, the following If/Then/Else object has two Else If conditions:

This object works as follows:

1. The expression 0<=A AND A<10 is evaluated, and the result is output on the Then terminal if the expression is true. (An expression is true if it evaluates to a non-zero value.)

2. Otherwise, the expression A<20 is evaluated, and the result is output on the corresponding Else If terminal if the expression is true.

3. If A<20 is false, the expression A<30 is evaluated, and the result is output on the corresponding Else If terminal if A<30 is true. If false, the result is output on the Else terminal.

See also

If/Then/Else


To Loop Part of a VEE Program

You can loop (repeat) part of your VEE program using one of the repeat objects described in the following list. You can include the Next and Break objects in a loop "hosted" by any of these objects. These are all under the Flow [image] Repeat menu.

Continue to scroll down for programming examples.

Summary of Repeat Objects

For Count

Outputs the count, starting with 0, repeating the number of times specified in the entry field. The default is 10, which causes the count to repeat 10 times, from 0 to 9.

For Range

Outputs a value on the data output pin repeatedly, starting with the value From, incrementing by the value Step on each repeat. For Range repeats until the output value is greater than the Thru value if Step is positive, or until the output value is less than the Thru value if Step is negative.

For Log Range

Similar to For Range, but on a log scale. The initial value output is From, but the nth value is From*exp10(n/(/Dec)). For Log Range repeats until the output value is greater than the Thru value if /Dec is positive, or until the output value is less than the Thru value if /Dec is negative.

For Each

For VEE array support, the For Each statement handles any VEE array of any number of dimensions (1-10), any dimension sizes, and any type. It will work in all ExecModes. For COM support, the For Each statement handles any COM (ActiveX) object that can be enumerated or looped. This type of object usually has a "Count" property and an "Item()" method to show it is a collection, though, strictly speaking, these are not required. COM/ActiveX is available in ExecModes 5 and higher. For .NET support, the For Each statement handles any .NET object that can be enumerated or looped through, for example StringCollection. This type of object also usually has a "Count" property and an "Item()" method to show it is a collection, though, strictly speaking, these are not required. .NET objects are available in ExecModes 6&7 and higher.

Until Break

Activates its data output pin continuously until a Break object operates within the thread.

On Cycle

Outputs the current time value periodically (the default period is 1 second) until a Break object operates within the thread.

Next

Causes the loop to begin its next iteration immediately.

Break

Causes the loop to terminate immediately.

Example: A For Count Loop

In the following example, the For Count object causes the Random Number object to operate 10 times. The For Count object's sequence output pin indicates when For Count is done operating (the loop is done repeating). The Collector collects the 10 random values in an array, but doesn't output the array until the sequence output pin of For Count activates the XEQ pin on the Collector.

Example: Taking a Reading Every Second

In the following example, the On Cycle object executes every second, causing the instrument panel object for the HP 34401A Multimeter to output a reading every second. This program produces simulated readings, since live mode is OFF for the HP 34401A. Each reading is output to the Logging AlphaNumeric display, and to the If/Then/Else object. The If/Then/Else object causes the Break object to operate, stopping the loop, on the first value that is greater than or equal to 7. The sequence output line from the Logging AlphaNumeric display to the If/Then/Else object ensures that the final reading is displayed before the loop stops. The AlphaNumeric object, configured for the Time Stamp format, reports the time of each reading as it is taken. This example is saved as manual02.vee in your manual examples directory (Help [image] Open Example).

Example: Parallel and Nested Loops

In the following example, the program includes parallel loops, which run concurrently, and a nested loop. Thread 1 and Thread 2 are parallel loops. Subthread 1a is nested within Thread 1. Multiple levels of nesting are allowed.

Avoid the following situations when using loops, which can cause a propagation paradox and lead to unpredictable results. Running programs like these in VEE 4 or higher execution modes will produce an error.

1. Do not cross connect parallel loops.

2. Do not merge loops (with a JCT or Math object, for example).

See also

manual03.vee and manual04.vee in manual examples directory Help [image] Open Example...


To Stop a VEE Program

Once you have started a VEE program, it will run according to the propagation rules until it finishes, and then stops.

Ways to stop a VEE program before it finishes propagating

Click the Stop button on the VEE toolbar.

Stop button

Click the Pause button to pause the program momentarily. Then click the Resume button to continue the program, or the Stop button to stop it.

Pause button

Resume button

Use Stop and Exit Thread objects. You can include a Stop or Exit Thread object in your program to define when it should terminate. For example, you can use an If/Then/Else object to conditionally branch to a Stop or Exit Thread object. When either of these objects operate, the program stops permanently just as though you clicked the Stop button.

Use Raise Error object. You can cause an error to occur, pausing your program, with the Raise Error object.

Shortcuts

Press CTRL+P on the keyboard to pause (not stop) a program.

Press CTRL+G on the keyboard to resume a paused program.

Note

In VEE 4 or higher execution modes, the Pause command is disabled if Disable Debug Features is turned on in Default Preferences.

See also

Default Preferences Exit Thread Stop To Trap an Error


To Change Default Colors

You can change the default colors for all of your programs.

1. Click the Default Preferences button on the VEE toolbar, then select the Colors tab in the dialog box.

Default Preferences button

2. Click on the Screen Element field or its arrow. The drop-down list displays the screen element choices.

3. Click on the screen element in the list that you want to change. The drop-down list disappears and the current color for that screen element is shown in the Color Value field.

4. Click on the Color Value button. The Select Color dialog box appears displaying a palette of the available colors. The screen element's current color selection is highlighted in the palette with a dashed outline. The color is also shown in the Preview area.

5. To select a new color, click on a different color in the palette, and then click on OK to return to the Default Preferences dialog box.

6. Make color selections for multiple screen elements as needed before saving your selections.

7. Choose how you want to save the new color selection for the screen element:

a. To save the color selection as a permanent default color, click on Save. This saves the new default color in your vee.rc file. The new color will be the default for future VEE sessions (until you change it again).

b. To use the new color selection only for the current VEE session (until you select File [image] New, Open, or Exit), click on OK.

c. To use the new color selection and save it with your VEE program, click on OK, then go to File [image] Save As… and check the Save colors and fonts with program box in the Options area.

d. To cancel the new color selection, click on Cancel.

e. To discard current settings and return to the settings in the defaults file vee.rc, click on Reset.

See also

Default Preferences, Using Colors, How to Pick Colors, To Use Color Coding


To Use Color Coding

Color Coding provides users more options to style Agilent VEE programs and makes Agilent VEE programs easier to read and write.

To Enable or Disable Color Coding

Color Coding is enabled by default. Users can disable it at any time. To disable Color Coding,

  1. On the File menu, click Default Preferences.

  2. In the Default Preferences dialog box, click Color tab.

  3. Under the Color tab, uncheck the Enable Color Coding. See the following figure.

With color coding enabled, Agilent VEE colors the title bar of detail view objects and the background of icon view objects according to the current color coding theme. Agilent VEE colors objects both in panel view and in detail view.

Agilent VEE updates the current opening VEE program automatically when the current color coding theme is changed or the color coding feature is enabled by checking the Enable Color Coding. When the Enable Color Coding is unchecked, VEE will use the classic blue theme to color objects.

Users can either use the default factory color coding theme provided by Agilent VEE or set their own themes. See To Change Color Coding Theme for more details.

To Import/Export Color Coding Themes

To share color coding theme with other developers, users need to export or import color coding themes. When users export a color coding theme, the theme will be saved in a XML file, then other users can use this theme by importing the XML file. Users can name the XML file and decide where to save it.

To Export or Import Color Coding Theme

  1. On the File menu, click Default Preferences.

  2. In the Default Preferences dialog box, click Color tab.

  3. Under the Color tab, click Import Color Coding... button, or Export Color Coding... button.

  4. In the opened dialog box, select the configuration file to import, or select a directory to save the configuration file.

See Also

To Change Color Coding Theme, Using Colors, How to Pick Colors, To Change Default Colors


To Change Colors for an Object

Every object has a Properties Window that you can reach from the object menu. You can change colors for a particular object from the Appearance category of this window.

1. Click with the right mouse button on the object to open its object menu. Select Properties from the object menu, then select the Appearance category from the properties window.

The colors that you can change depend on the particular class of object. Typically, you can change the background and text in the object's title bar and open view.

2. Select the property you want to change.

3. To select a new color, click on a different color from the list.

4. The new color selection appears in the object and overrides the default color. The change affects only the selected objects, and is saved when you save the program.

Shortcuts

Double-click on the object's title bar to access its Properties window.

Note

You can change Panel View colors for the Main Window, UserObjects, and UserFunctions using Properties on their object menus. The Panel Views for each context must exist before you can change their colors. The Main Window’s panel color is also applied to the Execution Window when the program runs. UserObject and UserFunction edit windows must be open to set their Panel View colors. For details about creating Panel Views, see the VEE Help contents under How Do I … Build an Operator Interface.

See also

Using Colors, How to Pick Colors, To Use Color Coding


To Change Color Coding Theme

1. Select the group you want to change its color, click the color square next to it, or

right click the group name, then choose Change Color....

The Select Color dialog box appears.

2. Select a color as desired.

3. Click OK button in the Select Color dialog box.

4. Right click the group name, then choose Apply to Sub Nodes.

5. Change colors for other groups as you need.

6. Click OK button in the Change Color Coding Theme dialog box.

1. In the Change Color Coding Theme dialog box, click the plus sign to expand the list and select the object you want to change its color.

2. Click the square next to the object, or

right click the object name, then choose Change Color...,

The Select Color dialog box appears.

3. Select a color as desired.

4. Click OK button in the Select Color dialog box.

5. Set colors for other objects as you need.

6. Click OK button in the Change Color Coding Theme dialog box.

To Change Color Coding Theme

You can either use the default color coding theme provided by Agilent VEE, or set your own color coding theme as desired.

To Change the Color Coding Theme:

  1. Click the Default Preferences button [image] on the VEE toolbar, and then select the Colors tab in the dialog box.

  2. Check the Enable Color Coding if it is not checked.

  3. Click the Change Color Coding... button. Change Color Coding Theme dialog box appears.

  4. Click the plus sign next to the VEE Objects list to open it.

All VEE objects are listed by their menu location and divided into five groups: Flow Controls, Device Controls, I/O Controls, Data Controls, and Display Controls. See the following figure.

You can change color for a group or for an individual object.

  • To change color for a group

  • To change color for an individual object

To discard the new color coding theme, click Cancel button. This will close the Change Color Coding Theme dialog box.

To reset to the VEE factory color coding theme, click Reset button.

Context Menu

In the Change Color Coding Theme dialog box, each group or object has a context menu that includes four commands. Change Color..., Apply to Sub Nodes, Copy Color, and Paste Color. See the following figure.

Change Color... opens the Select Color dialog box and let you to select a color for the selected group or object.

Apply to Sub Nodes applies the current color to all sub nodes under the selected group.

Copy Color copies the color of the selected group or object to the Copy/Paste buffer.

Paste Color sets the color of the selected group or object using the color in the Copy/Paste buffer.

Tips:

Instead of using the Select Color dialog box to change color for a group or an object, you can use Copy Color and Paste Color commands in the context menu to set color easily.

To Choose How You Want to Save the New Color Coding Theme:

After setting the color coding theme, you can choose how to save the new color coding theme in the Default Preferences dialog box.

  1. To save the color coding theme as a permanent default color coding theme, click on Save. This saves the new default color coding theme in your vee.rc file. The new color coding theme will be the default for future VEE sessions (until you change it again).

  2. To use the new color coding theme selection only for the current VEE session (until you select File [image] New, Open, or Exit), click on OK.

  3. To cancel the new color coding theme selection, click on Cancel.

  4. To discard current color coding theme and restore to the VEE factor color coding theme, click on Reset.

Note

Another way to change the default color coding theme is to import an existing color coding theme, then save it as described above.

note

After setting a color for a group of Agilent VEE objects in Default Preferences dialog box, Agilent VEE will color all objects in that group using the color coding theme. To set color for an individual object, change the Title BackColor in that object's Properties Window.

See Also

To Use Color Coding, Using Colors, How to Pick Colors, To Change Default Colors


To Change Default Fonts

You can change the default fonts for screen elements in the work area.

Note

1. Click the Default Preferences button on the VEE toolbar, then select the Fonts tab in the dialog box.

Default Preferences button

2. Click on the Screen Element field or its arrow. The drop-down list displays the screen element choices.

3. Click on the screen element that you want to change. The drop-down list disappears and the font value for that screen element is displayed.

4. Click on the Font Value button. The Select Font dialog box appears.

5. Click on the corresponding fields or their arrows to select a font name and size from the two drop-down lists. You can also select Bold and Italic by clicking on the appropriate checkboxes. Click on OK to return to the Default Preferences dialog box.

The font lists allow you to select any font that is installed on your system.

6. Make font selections for multiple screen elements as needed before saving your selections.

7. Choose how you want to save your font selection:

a. To save the new font selection as a permanent default font, click on Save. This will save the new default font in your vee.rc file. The new font will be the default for future VEE sessions (until you change it again).

b. To use the new font selection only for the current VEE session (until you select File [image] New, Open, or Exit), click on OK.

c. To use the new font selection and save it with your VEE program, click on OK, then go to File [image] Save As… and check the Save colors and fonts with program box in the Options area.

d. To cancel the new font selection, click on Cancel.

e. To discard current settings and return to the settings in the defaults file vee.rc, click on Reset.

See also

Default Preferences Using Fonts


To Change Fonts for an Object

Every object has a Properties window that you can reach from the object menu. You can change fonts for a particular object using this window.

Note

1. Click with the right mouse button on the object to open its object menu. Select Properties from the object menu, then select the Font property you want to change.

The fonts that you can change depend on the particular class of object. Typically, you can change fonts for the Title text and the Object text.

2. Click on the property for the text you want to change. A Select Font dialog box appears.

3. Click on the corresponding fields or their arrows to select a font name and size from the two drop-down lists. The font lists allow you to select any font that is installed on your system. You can also select Bold and Italic by clicking on the appropriate checkboxes.

To use the default font set in Default Preferences, click on the Default checkbox.

Click on OK to return to the Properties window.

The new font selection appears in the object and overrides the default font. The change affects only this particular object, and is saved when you save the program.

Shortcuts

Double-click on the object's title bar to access its Properties window.

See also

Using Fonts


To Change an Object Title

1. Select Properties from the object menu. The Properties Window appears.

2. Select title from the list and enter the new title.

Shortcut

Double-click on the object's title bar to access its Properties window.

Note

You can change the title for the Execution Window using Properties on the Main Window’s object menu. A Panel View for Main must exist first. This title is used as the program name in the Program Explorer. For details about creating Panel Views, refer to How Do I … Build an Operator Interface.


To Redo an Operation

An Edit menu selection that lets you Redo an operation.

Use

An Undo command reverses the outcome of an operation. You can return to the state before an Undo operation by using the Redo command

Notes

Redo is only available for operations supported by Undo. It is grayed out for all other operations.

Whenever you undo all operations and then initiate a new operation, the list of redo actions is cleared.

Review the Undo topic for redo stack limitations and known anomalies.

Location

From the Object Properties menu, select Redo.

From the Main Menu, Edit [image] Redo or CTRL+Y

From the Task Bar,

See Also

Undo


To Undo an Operation

An Edit menu selection that lets you reverse an operation performed in VEE. Not all operations can be undone.

Use

For Detail, the following operations can be undone in Main, UserObjects, and UserFunctions:

  • Cut a line

  • Add/Delete/Modify a terminal

  • Add/Delete a terminal in a UserObject or UserFunction

  • Object Moves, Alignment

  • Replace an Object

  • Cut/Paste an Object

  • Auto Scrolling

For Panel, the following operations can be undone in Panel, UserObjects, and UserFunctions:

  • Object Alignment

  • Object Deletes

Notes

Undo is only available for some operations. If the icon is grayed out, there is nothing to undo or the operation is not supported by undo.

Undo is location sensitive. For example, you can undo an Formula object delete. If you are entering a formula and delete a portion, you can undo this deletion if you would like. So, you can not only undo object actions but also text actions within objects.

Undo also has a very useful Tooltip ( [image]) that gives you insight into which undo operation is available.

When all operations are undone and a new operation is undertaken, you can only undo the most current operation. All operations previous to that can no longer be undone.

Actions that will invalidate either the current detail view and/or panel view undo stacks.

Deleting or cutting objects from the detail view that have corresponding views on the panel view causes the panel view's undo stack to be invalidated.

Creating a UserFunction from the selected objects in a detail view causes the detail view's undo stack to be invalidated. If there is a panel view associated with the source detail view, it is invalidated.

Creating a UserObject from the selected objects in a detail view causes the detail view's undo stack to be invalidated. If there is a panel view associated with the source detail view, it is invalidated.

Unpacking a UserObject into a detail view causes the destination detail view's undo stack to be invalidated.

Converting a UserFunction to a UserObject causes the target detail view's (where the UserObject is placed) undo stack to be invalidated. If there is a panel view associated with the UserFunction, its undo stack remains intact.

Making a UserFunction from a UserObject causes the source (location of the UOCarrier) detail view's undo stack to be invalidated. If there is a panel view associated with the UserObject, its undo stack remains intact.

Moving objects from one context to another causes both the source and destination detail view's undo stacks to be invalidated. If there is a panel view associated with the source context and one of the moved objects was on the panel, then the source's panel view undo stack will also be invalidated.

Adding any output on a panel driver that causes the creation of multiple outputs causes the undo stack of the associated context to be invalidated.

Changing an input or output terminal in any way (which includes adding, deleting or modifying name, type or shape) causes the undo stack of the context view that contains the UserObject's UOCarrier to be invalidated.

Known Anomalies

Drop an object of the type Declare Variable, ActiveX Control or XYGraph onto a detail view and then clone it. Delete one of the objects. Now rename the remaining object so that it has the same name as the object that was just deleted. Now press undo. Notice that the restored object has a different name because the name it wanted to use already existed. It silently got a new, unique name assigned to it.

If you have one context selected, press Paste to paste objects and then paste the objects into a different context, no undo actions will be registered. This same thing will happen on a drag-clone to a different context also.

Location

Edit [image] Undo or CTRL+Z

From the Task Bar -

See Also

Redo and Paste


To Find Objects by Searching for Text

Use the Find dialog box (Edit [image] Find) to search for objects. Find makes it easier for you to locate objects in a large program that contains many individual objects, UserObjects, and UserFunctions. You can specify the text, and set options to limit the search. Find is also available from its toolbar button.

Find button

1. Open the Find dialog box (Edit [image] Find or use the toolbar button). The dialog box appears.

2. In the Find: edit field, enter the text you want to search for.

3. On the General tab, set the limits you want to define for the text search.

4. After setting the limits, click Find. The search begins immediately.

Click Stop to stop a search that is in progress. Results found up to that time are displayed.

5. When the search finishes, the Find dialog box closes, and the Find Results dialog box appears. Find Results contains a list of objects that match the search criteria. See To View Results of a Find Operation for information about viewing objects in the list.

The following figure shows the Find dialog box set up to search for the text upper. The options set on the General tab show that the search results will include all objects in nested UserObjects, and show all occurrences that contain upper anywhere in a text string.

Shortcut

Press CTRL+F on the keyboard to open the Find dialog box.

Notes

To limit the scope of a search as listed for Search in, use the context menus in the Program Explorer. Click with the right mouse button on a UserObject, function, or folder name to raise a context menu, then click on Find. The Find dialog box appears with the Search in field containing the context name.

Find will not search for:

Panels or objects on panels.

Lines or line values.

Terminal values.

See also

To Explore the Program Structure

To Find Objects by Searching for Properties

To View Results of a Find Operation

Find

Find Results


To Find Objects by Searching for Properties

Use the Find dialog box (Edit [image] Find) to search for objects. Find makes it easier for you to locate objects in a large program that contains many individual objects, UserObjects, and UserFunctions. You can specify text and object properties as search criteria, and set options to limit the search. Find is also available from its toolbar button.

Find button

1. Open the Find dialog box (Edit [image] Find or use the toolbar button). The dialog box appears.

2. In the Find: edit field, enter the text you want to search for. You can leave this field blank if you plan to search only for object properties.

3. On the General tab, set Search nested UserObjects to control the search limit. If you entered text in the previous step, set the other limits you want to define for the text search.

4. On the Advanced tab, you can set up to three properties and their values. This limits the search results to objects containing the specified properties and values.

a. Click on a button under Property to set a property name. The Property Name dialog box appears containing all available object properties.

Scroll through the list and select a property by double-clicking its name. The property name appears on the button.

b. The button under Value changes mode relative to the selected property. The value-selection methods include:

Select a value from a drop-down list.

Select a value from a dialog box.

Select a color from the color palette.

Type in a text or numeric value.

c. If necessary, click Reset to return to the single default setting for Property (Object Type) and Value (All Types).

5. After setting the search criteria, click Find. The search begins immediately.

Click Stop to stop a search that is in progress. Results found up to that time are displayed.

6. When the search finishes, the Find dialog box closes, and the Find Results dialog box appears. Find Results contains a list of objects that match the search criteria. See To View Results of a Find Operation for information about viewing objects in the list.

The following figure shows the Find dialog box set up to search for the text upper. The Advanced tab shows that the search results will include only those objects with the specified property values. Notice that the Adv status indicator (upper-right corner) is highlighted when you include property values in a search.

Shortcut

Press CTRL+F on the keyboard to open the Find dialog box.

Notes

To limit the scope of a search as listed for Search in, use the context menus in the Program Explorer. Click with the right mouse button on a UserObject, function, or folder name to raise a context menu, then click on Find. The Find dialog box appears with the Search in field containing the context name.

Find will not search for:

Panels or objects on panels.

Lines or line values.

Terminal values.

See also

To Explore the Program Structure

To Find Objects by Searching for Text

To View Results of a Find Operation

Find

Find Results


To View Results of a Find Operation

After using Find to search for objects containing specific text and properties, the Find Results tool window appears with information about the matches. Find Results gives you an easy way to view the objects that were found. The results are retained until you click the Clear button or you do a new Find letting you open and close Find Results as needed (Edit [image] Find Results).

Find Results button

The following figure shows an example of Find Results listing the objects containing the text upper.

Using the Find Results Tool Window

Double-click on a line in the list to bring the listed object, UserObject, or UserFunction into view in the work space. UserObject and UserFunction edit windows are opened; individual objects are highlighted.

Click on column headings to sort the list’s order.

Click the left or right arrow buttons to bring the previous or next item into view.

Previous and Next buttons

Click the Find button to open the Find dialog box, and start a new search. This closes Find Results, and clears its contents.

Find button

Click the Clear button to clear the list.

Clear button

The Adv status indicator is highlighted when the search specified property values on the Find dialog box’s Advanced tab.

Ways to Open the Find Results Tool Window

Besides from the Find dialog box, you can open the Find Results tool window from Program Explorer and Watch Window.

From Program Explorer,

  • Right click a variable and choose References. The Find Results tool window appears listing all objects containing the variable.

  • Right click a UserFunction and choose Calls or Called by. The Find Results tool window appears listing all UserFunctions that call this UserFunction or called by this UserFunction.

From Watch Window,

  • Right click a variable and choose References. The Find Results tool window appears listing all objects containing the variable.

Shortcut

Press CTRL+R on the keyboard to open the Find Results dialog box.

Note

The Find Results menu item and toolbar button are grayed out until a Find is done.

The Find Results contents from a previous Find operation are cleared whenever you open the Find dialog box again.

See also

To Find Objects by Searching for Properties

To Find Objects by Searching for Text

Find

Find Results

Copyright (c) 1991-2007 Agilent Technologies, Inc.


To Explore the Program Structure

Use the VEE Program Explorer (View [image] Program Explorer) to explore a program’s entire structure. The Program Explorer makes it easy to access information, navigate a program, or change program contents. You can quickly open and close the Program Explorer by using its toolbar button.

Program Explorer button

To view the program structure

1. Open the Program Explorer. The window opens at the left side of the VEE work space.

2. Click on the controls (+ and -) to expand and contract the tree view. Depending on the program’s contents, the Program Explorer shows a complete list of the following information:

UserObject hierarchy starting at the Main UserObject.

Local UserFunctions.

Imported UserFunction Libraries and associated functions.

Imported Compiled Libraries and associated functions.

Imported Remote UserFunction Libraries and associated functions.

Global variables, both declared and undeclared.

Declared local variables under the appropriate context.

Declared library global variables under the appropriate library.

The following figure and list show the icons used by the Program Explorer to represent the various contexts, and variables:

1. Represents the entire program.

2. Represents UserObjects.

3. Represents local, imported, and remote UserFunctions.

4. Represents Compiled Functions.

5. Represents declared and undeclared Global Variables and declared Library Variables.

6. Represents local variables.

7. Represents containers for categories such as library names, Globals, and UserFunctions.

8. Represents event handlers.

To use the context menus

The Program Explorer’s context menus give you access to objects and information in a program. To open the context menus, click with the right mouse button on an item in the list, then click on a menu choice. The menus’ contents change depending on the item.

To view or document program information, use the following menu choices if available on a particular context menu. The action for a menu choice changes relative to the item’s location in the program structure :

Print prints the program, UserObject, or function (see Print Program and Print Objects).

Document saves the program, UserObject, or function documentation (see Save Documentation)

Calls finds the UserFunctions the item calls.

Called By finds the UserObjects or functions that call the item.

View opens a dialog box with the variable’s current value.

To access the program’s contents to make changes, use the following menu items if available on the particular context menu:

Open brings the item into view in the work space. This is the same as double-clicking the item.

Find opens the Find dialog box (see Find). This also limits the scope of a search to the bounds of the highlighted item instead of the entire program.

Generate [image] lets you create one of the following objects containing an expression referencing a UserFunction title. You can place the generated object in another part of the program (see Call, Formula, If/Then/Else, ShowPanel, HidePanel)

Cut opens a Confirm dialog box, which lets you remove the item from the program.

Description opens the item’s Description dialog box (see Description).

Properties opens the item’s Properties Window (see Properties (Object)).

References finds the objects that use the variable.

Shortcuts

To view a UserObject, UserFunction or other context in the work space, double-click the context name in the Program Explorer.

To view the current value of a variable, double-click the variable name. A dialog box appears with information about the variable’s type, shape, and data.

Program Explorer button

See also

Default Preferences


Minimap

A View menu item that opens the Minimap tool window. Minimap is an outline map of the entire detail view with a red rectangle box indicating the visible portion. The red rectangle shows the relative location of the visible area in the entire detail view.

Use

Minimap shows an outline of the entire detail view with a red rectangle indicating the visible portion.

Using Minimap, you can quickly jump to a location in a detail view. To go to a certain location in a detail view,

  • Click the location on the Minimap,

- OR -

  • Drag the red rectangle to the location on the Minimap.

Context Menu

Print... -- Print a bitmap of the entire detail view. You can resize the Minimap window to change the print size of the bitmap.

Print Auto Fit ... -- Automatically resize the bitmap of the entire detail view to one page size and print the bitmap. The width of the resized bitmap is the width of the page, and the height of the bitmap will be in proportion to its width.

Copy To Clipboard ... -- Copy a bitmap of the entire detail view to the Clipboard.

Send By Email ... --- Send a bitmap of the entire detail view as an attached file by email.

Save To File ... -- Save a bitmap of the entire detail view to a bitmap file.

note

Minimap is available only in detail view. It will be automatically hidden in Panel view or at runtime.

Example

Shortcuts

Press [image] button on VEE Toolbar.

Location

View [image] Minimap

See Also

To Navigate Programs


Using Online Help

Here are some ways to teach yourself more about VEE.

1 First, run the Multimedia Tutorials located in the Help [image] Welcome menu. The tutorials demonstrate many of the main features of VEE. They will help bring you up to speed quickly. The tutorials display screen demonstrations of VEE programs being built and run, and describe what you are seeing. The tutorials also introduce key concepts for using VEE effectively.

2 Once you become familiar with VEE, look for more information in the Help entries in the object menus. You can experiment with the objects until you understand how they work. If you need to know more about an object, the object menus give you the most specific information. Consult them first.

3 To use the Help contents, index, or search capabilities, open Help on the main VEE menu bar.

note

To review how to open the main Help facility and a listing of the Help contents, refer to “Getting Help".

Using the Help Facility

Online Help provides information on the following topics:

• All menu items, as well as shortcuts for most of them

• Instrument driver information

• Frequently performed tasks and many example programs

• Definition of VEE terms

• Using the help facility

• VEE version

You can browse, use the keyword index, use hyperlinks to related topics, or even do a search. There are many Help features available in VEE that you can use as you develop programs.

note

VEE also includes other helpful features for developing and debugging programs, such as line probe. For more information, refer to “Debugging Programs in Agilent VEE"

Displaying Help about an Object

To get help on an object, click on the object menu button and select Help.

• Select Flow [image] Repeat [image] For Count to create a For Count object. Click on object menu and select Help. The Help topic appears describing For Count.

• Select Device [image] Formula to create a Formula object. Click on the object menu and select Help. The Help topic appears describing the particular formula displayed in the Formula object.

• Select Device [image] Function & Object Browser. Select any combination of choices and click on Help. The Help topic appears for the particular object that is selected.

Finding the Menu Location for an Object

To find the location for an object in the menus, and to display the information about that object, select Help [image] Contents and Index, click on the Index tab, type in the name of the object, and click Display.

For example, select Help [image] Contents and Index, click on the Index tab, and type in Collector. Click Display to display the Help topic for the Collector object.

Other Practice Exercises Using the Help Facility

• Look up the short-cut to delete an object.

Select Help [image] Contents and Index [image] How Do I... Use the Keyboard Shortcuts [image] Editing Programs [image] To Cut an Object or Text.

• Look up the word “terminal.”

Select Help [image] Contents [image] Reference [image] Glossary [image] Terminal.

• Look up the VEE version number.

Select Help [image] About VEE Pro.

• Find out what is new in this version of Agilent VEE.

Select Help [image] Contents and Index [image] What’s New in Agilent VEE Pro.


Documenting Agilent VEE Programs

To Document Agilent VEE Programs

By using the File [image] Save Documentation... command, you can automatically generate program documentation. VEE lists all objects, with key settings, the default and user names, the Description entries, and any “nesting.” For example, objects within a UserObject are nested one level from the main VEE environment, and these levels are indicated by numbers.

You can also document individual objects using a Description.

See Also

To document Objects with Description Dialog Boxes,

To Generate Documentation Automatically


Documenting Objects with Description Dialog Boxes

To Document Objects with Description Dialog Boxes

All objects have a Description item in their object menus, which provides a dialog box to accept documentation on that particular object. This documentation file also provides a way to correlate the documentation with screen dumps. In this section, you will add an entry to the Description dialog box.

1 Open the Random.vee program.

2 Delete the template information, as shown below, from the Description.

3 Note that the Description box is a rich text format (RTF) box. You can retrieve files from any program that creates RTF files. The RTF format gives you a great deal of flexibility in the presentation of your text data.

4 In the Main object menu, click Description. Type text in the dialog box: The Random.vee program generates random numbers. Click OK when you are done.

note

The entries in the Description dialog box will not be visible to users unless they access them through the object menu. Also, notice that you can insert a file in this dialog box.

See Also

To Generate Documentation Automatically


Generating Documentation Automatically

To Generate Documentation Automatically

Follow these steps to generate a file of program documentation:

1 Open Random.vee. Click File [image] Save Documentation.... Enter the file name using a *.txt suffix (Random.txt, for example), then click Save. By default, the file is saved in the folder C:\My Documents\VEE Programs.

2 Open the file in any text editor to view or print. The following three figures show the documentation file using the Notepad program in Windows.

The first figure shows the beginning of the file, with information on the file, revision dates, and system I/O configuration.

The Beginning of the Documentation File

Source file:"C:\\ My Documents \\ VEE Programs \\ Random.vee

Date documented: Wed Sep 27 10:31:08 2006

VEE revision: 8.0

Execution Mode: VEE 8

Convert Infinity on Binary Read: no

I/O Configuration

My Configuration (C:\vee.io)

The Middle of the Documentation File

M: Main

Device Type : Main

customHelpMenuName :

customHelpMenuDescription:

customHelpMenuHelpLink :

Declared Name : Main

Declared Scope : Local to Context

Context is secured : off

TrigMode : Degrees

PopupPanelTitle : Untitled

PopupMoveable : on

Delete Globals at Prerun : off

In the above figure, the VEE objects are described along with their settings. The number before each object indicates where the object is located. For example, the first object in Main is listed as M1. The last figure shows the remainder of this documentation file for your reference.

The Remainder of the Documentation File

M.0: Main/Int32

Device Type : Constant

Output pin 1 : Int32

customHelpMenuName :

customHelpMenuDescription:

customHelpMenuHelpLink :

Declared Name :

Declared Scope : Local to Context

Wait For Input : off

AutoExecute : off

InitializeAtPrerun : off

InitializeAtActivate : off

InitialValue : 0

EnableStepping : off

DetentSize : 1

DataShape : Scalar

ArraySize : 10

ArraySizeFixed : off

ShowArrayIndices : on

EnableEditing : on

Int32 Value : 0

M.1: Main/Int32

Device Type : Constant

Output pin 1 : Int32

customHelpMenuName :

customHelpMenuDescription:

customHelpMenuHelpLink :

Declared Name :

Declared Scope : Local to Context

Wait For Input : off

AutoExecute : off

InitializeAtPrerun : off

InitializeAtActivate : off

InitialValue : 0

EnableStepping : off

DetentSize : 1

DataShape : Scalar

ArraySize : 10

ArraySizeFixed : off

ShowArrayIndices : on

EnableEditing : on

Int32 Value : 1

M.2: Main/random(low,high)

Device Type : Formula

Input pin 1 : low (Any, Any)

Input pin 2 : high (Any, Any)

Output pin 1 : Result

customHelpMenuName :

customHelpMenuDescription:

customHelpMenuHelpLink :

Declared Name :

Declared Scope : Local to Context

Formula : random(low,high)

M.3: Main/AlphaNumeric

Device Type : AlphaNumeric

Input pin 1 : Data (Any, Any)

customHelpMenuName :

customHelpMenuDescription:

customHelpMenuHelpLink :

Declared Name :

Declared Scope : Local to Context

ClearAtPrerun : on

ClearAtActivate : on

ShowArrayIndices : on

M.4: Main/Note Pad

Device Type : Note Pad

customHelpMenuName :

customHelpMenuDescription:

customHelpMenuHelpLink :

Declared Name :

Declared Scope : Local to Context

Note Contents : {\\rtf1\\ansi\\ansicpg1252\\deff0\\deflang1033{\\fonttbl{\\f0\\fnil\\fcharset0 Times New Roman;}}\r\n{\\colortbl ;\\red0\\green0\\blue0;}\r\n\\viewkind4\\uc1\\pard\\cf1\\f0\\fs24 This program , Random, generates a real number between 0 and 1, then displays the results.\\par\r\n}\r\n

NOte

After you run the Save Documentation command, run a File => Print Program command to put identification numbers on the objects, so you can match the text documentation to the printer output.

See Also

To Document Objects with Description Dialog Boxes


Merging Agilent VEE Programs

To Merge Agilent VEE Programs

The easiest way to leverage existing programs is to merge a past program with the current test. You can re-use programs by merging them and then editing them to suit your current needs.

The File [image] Merge... command adds the contents of a program or set of saved objects into the work area while keeping the existing contents of the work area. By default, File [image] Merge... displays a directory of programs that are shipped with VEE. They include commonly needed programs such as a bar chart display and a data entry keypad for user input (such as ID numbers).

See Also:

Lab 9-4: Merging a Bar Chart Display Program


Using Library Objects

To Use Library Objects

VEE also includes a library of objects that you can ‘‘Merge'' into your programs. The library objects are installed as part of the VEE installation process in the following directory:

C:\Program Files\Agilent\VEE Pro 8.0\Lib\

Most library objects are UserObjects that encapsulate individual objects. You can create UserObjects for the library and save them at:

C:\Program Files\Agilent\VEE Pro 8.0\Lib

Formula Objects

Formula objects that you can merge into your program are also available. Each of these objects performs a useful conversion function, such as degrees to radians.

The files are located in:

C:\Program Files\Agilent\VEE Pro 8.0\Lib\convert\


Using the Keyboard Shortcuts

You can use keyboard shortcuts to perform many common VEE tasks. Note that the keyboard shortcuts are not case sensitive.

VEE tasks | Shortcuts
Controlling Files
To Clear the Work Area | CTRL+N
To Open a VEE Program File | CTRL+O
To Save a VEE Program to a File | CTRL+S
To Save a VEE Program to a New File | CTRL+W
To Print or Copy the VEE Window | Alt+Print Screen
To Exit VEE | CTRL+E
Editing Programs
To Navigate the VEE Menu | Alt+...
To Raise the Function & Object Browser | CTRL+H
To Select Objects | CTRL, CTRL+A
To Raise the Pop-Up Edit Menu | Right mouse button
To Raise the Pop-Up Object Menu | Right mouse button
To Edit a Formula Object’s Expression | Enter, Delete, Backspace, Up/Down arrows, Right/Left arrows, Shit+End, Home+Shift, Page Up, Page Down, Double Click, Triple Click
To Edit a Transaction | CTRL+C, CTRL+X, CTRL+V, CTRL+Z, CTRL+Y, CTRL+Up, CTRL+Down, Shift+Up/Down
To Move the Text Cursor | Up arrow, Down arrow, Left arrow, Right arrow
To Cancel an Edit in an Entry Field | Esc
To Cancel Edits in a Dialog Box | Esc
To Copy or Clone an Object or Text | CTRL+C, CTRL+ LButton and drag
To Cut an Object or Text | CTRL+X
To Add a Data Input Terminal to an Object | CTRL+A
To Add a Data Output Terminal to an Object | CTRL+A
To Delete a Terminal from an Object | CTRL+D
To Delete a Line | Shift+CTRL+LButton
To Refresh the VEE Window | CTRL+Q
Navigating Programs
To View the Main Window | CTRL+M
To Select Windows and Scroll the Work Areas | CTRL+Tab or CTRL +F6 , CTRL+Shift+Tab or CTRL+Shift+F6 , Page Down/Up, Shift+Page Down/Up, Home, Shift+Home
To Raise the Find Dialog Box | CTRL +F
To Raise the Find Results Dialog Box | CTRL +R
To Navigate an Operator Interface Panel | Tab, Shift+Tab
Debugging Programs
To Run, Pause, Step, or Resume a VEE Program | CTRL+G (or F5), CTRL+P , F10, CTRL+T OR F11, Shift +F11
To View Data on a Line | Shift+LButton
To View Connections to an Object | Shift+LButton
To View Downstream Connections to an Object | CTRL+Shift+LButton
To Toggle Breakpoint Settings | CTRL+B
To Get Help on an Object or Dialog Box | F1
Others
To expand the entire instrument list in Instrument Manager | *
To show/hide object terminals | CTRL+U
To stop a running program | Shift + F5


To Clear the Work Area

Press CTRL+N. You will be prompted to save changes to the current program (shortcut for the New button on the toolbar, and for File [image] New).


To Open a VEE Program File

Press CTRL+O. You will be prompted for a file name to open (shortcut for the Open button on the toolbar, and for File [image] Open).


To Save a VEE Program to a File

Press CTRL+S. The program will be re-saved to the current file, or you will be prompted for a file name (shortcut for the Save button on the toolbar, and for File [image] Save).

Note

Saved files may not be backward compatible. A version 5 file retrieved into version 6 and saved is no longer compatible with version 5.


To Save a VEE Program to a New File

Press CTRL+W. You will be prompted for a new file name, and the program will be saved there (shortcut for File [image] Save As).

Note

Saved files may not be backward compatible. A version 5 file retrieved in version 6 and saved is no longer compatible with version 5.


To Print or Copy the VEE Window

To copy the VEE window to the MS Windows Clipboard, press Alt+Print Screen with VEE as the active window. (shortcut for the Print Screen button on the toolbar, and for File [image] Print Screen). From the Clipboard, you can paste the VEE window into other Windows applications that can use the Clipboard.

Note that these shortcuts allow you to capture the VEE screen even when a dialog box is present.


To Exit VEE

Press CTRL+E to exit VEE (shortcut for File [image] Exit).


To Add a Data Input Terminal to an Object

Press CTRL+A with the pointer in the input terminal area to insert another data input terminal at the pointer location (shortcut for: object menu [image] Add Terminal [image] Data Input). If you have just edited a field in the object, you may need to click the left mouse button first, and then press CTRL+A.

To add a terminal using CTRL+A, the Show Terminals object property must be active and the pointer must be over the input terminal area at the left side of the object.


To Add a Data Output Terminal to an Object

Press CTRL+A with the pointer in the output terminal area to insert another data output terminal at the pointer location (shortcut for: object menu [image] Add Terminal [image] Data Output). If you have just edited a field in the object, you may need to click the left mouse button first, and then press CTRL+A.

To add a terminal using CTRL+A, the Show Terminals object property must be active and the pointer must be over the output terminal area at the right side of the object.


To Cancel an Edit in an Entry Field

Press Esc to cancel an edit in a type-in entry field.


To Cancel Edits in a Dialog Box

Press Esc to cancel all edits in a dialog box (equivalent to clicking on the Cancel button).


To Copy or Clone an Object or Text

Select the object(s) or text you want to copy, then press CTRL+C. This puts the object(s) or text into the cut-copy-paste buffer (shortcut for the Copy button on the toolbar, and for Edit [image] Copy). Note: Text is copied only with CTRL+C, not with the toolbar button or menu choice.

To paste the copied object(s) into the work area, use CTRL+V (shortcut for the Paste button on the toolbar, and for Edit [image] Paste). Then click on the location where you want to put the object(s). Any lines connecting copied objects are retained. Note: Text is pasted only with CTRL+V, not with the toolbar button or menu choice.

To clone the selected object(s), while pressing CTRL, click with the left mouse button and drag the cloned object(s) to a new location.

You can copy object(s) and text from one work area, then paste into another work area. In Windows, you can also copy from one instance of VEE, then paste into another instance of VEE. Objects and text can be copied to other Windows applications that can use the Clipboard.


To Cut an Object or Text

Select the object(s) or text you want to cut, then press CTRL+X. This puts the object(s) or text into the cut-copy-paste buffer. (shortcut for the Cut button on the toolbar, and for Edit [image] Cut). Note: Text is cut only with CTRL+C, not with the toolbar button or menu choice.

You can replace an object cut by mistake using CTRL+V (shortcut for the Paste button on the toolbar, and for Edit [image] Paste). Then click on the location where you want to put the object. The object and its connections are restored. You can also undo the cut using Edit > Undo from the main menu. Note: Text is pasted only with CTRL+C, not with the toolbar button or menu choice.

Objects and text cut from one work area, can be pasted into another work area. Also, objects and text cut from one instance of VEE, can be pasted into another instance of VEE. Objects and text can be pasted into other Windows applications that can use the Clipboard.


To Delete a Line

Press and hold Shift+CTRL, and click the left mouse button with the pointer over or near the line you want to delete (shortcut for the Delete Line button on the toolbar, and for Edit [image] Delete Line). You can use Undo on this action.


To Delete a Terminal from an Object

Press CTRL+D with the pointer over the terminal to be deleted. (A shortcut for: object menu [image] Delete Terminal [image] Input or object menu [image] Delete Terminal [image] Output.) If you have just edited a field in the object, you may need to click the left mouse button first, and then press CTRL+D.

To delete a terminal using CTRL+D, the Show Terminals object property must be active and the pointer must be over the terminal to be deleted.

You can undo the deletion by pressing CTRL+Z.


To Edit a Formula Object’s Expression

The following are the editing actions available when you are entering an expression in a Formula object. In general, if you can do it in an RTF document, you can do it in the Formula object.

Press Enter to insert a carriage return, and move the cursor to the next line. Doing this in the middle of a line breaks the line and inserts characters after the cursor onto the next line. Doing this at the beginning of any line inserts a blank line above it.

Press Delete at the right end of a line to merge the next line into this line, retaining the current cursor position.

Press Backspace at the left end of a line to merge this line with the line above it, retaining the current cursor position.

The up- and down-arrows move the cursor vertically up and down the lines, retaining the cursor’s horizontal position. When the cursor is on the last line, pressing the down-arrow adds a new line. The right- and left-arrows move the cursor right and left.

From the left end of a line, Shift End highlights the entire line. From the right end of the line, a Home Shift highlights the entire line.

Page up and page down function as expected.

A double-click on a word highlights the word. A triple-click on a line highlights the entire line.

See Also

Code Completion, Code Insight


To Edit a Transaction

When the edit box of a transaction-based object (for example, the Sequencer or To File objects) owns the focus, you can use following shortcuts:

CTRL+X to cut the selected transaction(s) to the "cut-and-paste" buffer (object menu [image] Cut Trans).

CTRL+V to paste transaction(s) from the "cut-and-paste" buffer at the pointer location (object menu [image] Paste Trans).

CTRL+C to copy the selected transaction(s) to the "cut-and-paste" buffer (object menu [image] Copy Trans).

Delete to delete the selected transaction(s) in the list (object menu [image] Delete Trans).

Insert to insert a transaction before the selected transaction(s) (object menu [image] Insert Trans).

CTRL+Z to undo last operation.

CTRL+Y to redo last operation.

CTRL+Up to move the selected transaction up (object menu [image] Move Trans Up).

CTRL+Down to move the selected transaction down (object menu [image] Move Trans Down).

Shift+Up/Down to select multiple transactions.

Note

Move operations only support single-transaction operations.

For further information about transactions, refer to Tell me about... I/O Transactions in Contents and Index under Help menu.


To Move the Text Cursor

In alphanumeric text entry areas (for example, the Note Pad object) use the cursor-control arrow keys (up-arrow, down-arrow, left-arrow, right-arrow) to move the cursor in the direction of the arrow.


To Navigate the VEE Menu

You can navigate the VEE menu by using the keyboard menu accelerators. Each menu item has an underlined letter, which acts as an accelerator in conjunction with the Alt key. The keyboard accelerator letters are case insensitive. In other words, even though the underlined letter may be capitalized, you can use the lower case letter as the accelerator. Let's look at an example.

In the Device menu the D is underlined (but d works fine as the accelerator) and in the Data menu the t is underlined:

On the PC, press Alt+d to select the Device menu or Alt+t to select the Data menu.

Each sub-menu has its own accelerators, which you can use to navigate further down the menu tree. For example, to select Data [image] Continuous [image] Real64 Slider:

On the PC, press Alt+t, then Alt+i, then Alt+r.


To Raise the Function & Object Browser

Press CTRL+H or Backspace (shortcut for the fx button on the toolbar, and for Device [image] Function & Object Browser).


To Raise the Pop-Up Edit Menu

Press the right mouse button with the pointer over an empty part of the Main Window work area. (This works for UserObject and UserFunction work areas as well.)


To Raise the Pop-Up Object Menu

Press the right mouse button with the pointer over any part of an object.


To Refresh the VEE Window

Press CTRL+Q to refresh the VEE window.


To Select Objects

To select one object, click the left mouse button with the pointer over the object. The selected object is highlighted with a shadow.

To select and un-select an object, press and hold CTRL, and click the left mouse button with the pointer over the object. The object becomes selected if it is not currently selected. If the object is currently selected, it becomes un-selected.

There are three ways to select multiple objects.

  • Press and hold CTRL, and click the left mouse button on each object that you want to select.

  • While pressing CTRL, click and hold the left mouse button, then drag the outline box across the desired objects. Object selections are toggled.

  • Press CTRL+A to select all objects in the current work area (Main Window, UserObject, or UserFunction) whether they are currently selected or not (shortcut for Edit [image] Select All).


To View the Main Window

Press CTRL+M (shortcut for View [image] Main).


To Select Windows and Scroll the Work Areas

To move through a stack of open windows in the VEE work space:

Press CTRL+Tab or CTRL +F6 to move down through a stack of windows from the top.

Press CTRL+Shift+Tab or CTRL+Shift+F6 to move up through a stack of windows from the bottom.

With the pointer anywhere within the work area of the Main, a UserObject, or a UserFunction window:

Press Shift+up-arrow, Shift+down-arrow, Shift+left-arrow, or Shift+right-arrow to scroll the work area in the direction of the arrow key.

Press Page Down to scroll the work area up one screen.

Press Page Up to scroll the work area down one screen.

Press Shift+Page Down to scroll the work area left one screen.

Press Shift+Page Up to scroll the work area right one screen.

Press Home to move the upper left corner of the program to the upper left corner of the work area.

Press Shift+Home to move the lower right corner of the program to the lower right corner of the work area.


To Raise the Find Dialog Box

Press CTRL+F (shortcut for the Find button on the toolbar, and for Edit [image] Find).


To Raise the Find Results Dialog Box

Press CTRL+R (shortcut for the Find Results button on the toolbar, and for Edit [image] Find Results). This command is available after a successful Find operation.


To Navigate an Operator Interface Panel

If you or another VEE programmer have created an operator interface panel view in a VEE program, you can navigate the panel with the following keys:

Press Tab and Shift+Tab to move from one field in the operator interface panel to the next. The Tab key moves focus forward, and Shift+Tab moves focus backward from field to field. When a type-in field has focus (indicated by an inverse highlight), you can edit it. When a button has focus (indicated by a dashed outline), you can "push" it as described below.

Press the space bar to "push" a button that currently has focus.

Use the appropriate alphanumeric keys to edit a type-in field that currently has focus. Press Enter or Return to complete and accept the edit, or press Esc to abort the edit.

Press Enter or Return to "push" the default button in the operator interface panel, if one has been defined by the programmer.

Operator interface panel views and how to use them are covered in detail in VEE Help under How Do I... Build an Operator Interface.


To Run, Pause, Step, or Resume a VEE Program

Press CTRL+G (or F5) to run a VEE program (shortcuts for the Run button on the toolbar, and for Debug [image] Run/Resume).

Press CTRL+P to pause a running VEE program (shortcut for the Pause button on the toolbar, and for Debug [image] Pause). (To stop a program, you must click the Stop button on the toolbar.)

Press F10 to step a paused VEE program (shortcut for the Step Over button on the toolbar, and for Debug [image] Step Over).

Press CTRL+T (or F11) to step a paused VEE program (shortcuts for the Step Into button on the toolbar, and for Debug [image] Step Into).

Press Shift-F11 to step a paused VEE program (shortcut for the Step Out button on the toolbar, and for Debug [image] Step Out).

Press CTRL+G to resume a paused VEE program (shortcut for the Resume button on the toolbar, and for Debug [image] Run/Resume).


To View Data on a Line

Click the left mouse button with the pointer over the line you want to probe (shortcut for Debug [image] Line Probe). Information about the last container of data on the line is displayed.


To View Connections to an Object

Press and hold Shift, and click the left mouse button with the pointer over the object you want to probe (shortcut for Debug [image] Object Probe). All lines and objects connected to the probed object are highlighted.


To Toggle Breakpoint Settings

Select one or more objects, then press CTRL+B (shortcut for the Toggle Breakpoint button on the toolbar, and for Debug [image] Toggle Breakpoint).

The breakpoint for each selected object is switched to the opposite state.


To Get Help on an Object or Dialog Box

When an object is selected, press F1 to open the Help topic for that object (shortcut for: object menu [image] Help). If several objects are selected, the Help topic opens for the object that was selected first. If no objects are selected, the main Help Contents window opens.

When a dialog box, such as Default Preferences is open, press F1 to open the Help topic for that dialog box (shortcut for clicking on the Help button).


To Change the Printing Preferences

You can change the default preferences that VEE uses for printing your program.

To display the Default Preferences dialog box, select File >Default Preferences. Then click on the Printing tab.

After changing preferences, choose how you want to save the settings:

a. To save the settings as new default values, click on Save. This saves the new values in your vee.rc file. These preferences will be the defaults for future VEE sessions (until you change them again).

b. To use the new preferences only for the current VEE session (until you select File [image] New, Open, or Exit), click on OK.

c. To set preferences back to default values, click on Reset.

d. To cancel the changes, click on Cancel.

To change the printer palette

1. The Screen Element and B&W Printer Darkness fields both provide drop-down lists. To change the darkness (gray-scale value) for the Detail View, click on B&W Printer Darkness (or the arrow).

2. Now click on the desired darkness. If you want the Detail View background to be white, click on 0 % (White). (Most VEE elements are set to Automatic grayscale by default. The colors in your screen palette are automatically converted to appropriate shades of gray.)

To change the printout contents

1. To change the Print Magnification value, click on the field and edit the value. (The default is 75 percent. You can set values greater or less than 100 to change the size of the printed image.)

2. Select other printing options to customize a report package:

Print Header and Index Page prints a header at the top of each page containing file location and a date/time stamp, and an index listing report sections with page numbers.

Print Program Explorer prints an expanded view of the Program Explorer.

Print Cover Page includes the program’s file name, revision date, execution mode, save-file format, and the VEE revision number.

Print I/O Configuration prints the instrument configuration’s expanded tree view. You can see the instrument configuration in I/O [image] Instrument Manager…

See also

To Change Default Fonts


To Set Up a Printer

VEE supports the HP LaserJet, HP DeskJet, and most PostScript™ printers for VEE printing and for plotting operations. In addition, VEE supports most HP-GL compatible plotting devices.

To change the printer configuration for VEE, follow these steps. (In most cases the default printer configuration will work.)

1. Select File [image] Print Setup. The Print Setup dialog box appears.

2. Select the printer configuration that you want, using the standard Microsoft Windows techniques for the Print Setup dialog box.

3. Click on Properties for more printing options, or click on OK to confirm your selections.


To Print the VEE Work Space

You can print the work space contents currently visible in the VEE Window.

1. To print the work space immediately, click the Print Screen button on the toolbar.

Print Screen button

or

1. Use File [image] Print Screen. The Print dialog box appears.

2. If the printing configuration is acceptable, click on OK to print the VEE work space. Or change the parameters and then click on OK. The work space is printed including the toolbar and status bar.

Tip

You can also print the whole work space programmatically using the Print Screen object.

Shortcuts

These shortcuts let you capture the VEE screen even when a dialog box is displayed, and the toolbar button and menu are inaccessible:

Capture the VEE window in the Microsoft Windows clipboard by pressing Alt+Print Screen on the keyboard at any time. (If a program is running, it will pause momentarily.) You can then paste the image into Microsoft Paint or other Windows graphics applications.

See also

Print Screen Object


To Print a VEE Program

You can print a representation of the program currently open in the VEE Window. The entire program, or smaller parts, can be printed.

To print an entire program

1. Select File [image] Print Program. The Print Options dialog box appears. These options let you control the level of program detail that is printed:

Print Nested UserObjects prints the contents in all UserObjects contained in the program.

Print Object Views prints the open views of objects that contain useful information.

The remaining options are set according to the default preferences described in To Change the Printing Preferences . You have the opportunity to change them each time you print a program.

2. Click OK. The Print dialog box appears. Change the printing configuration if desired.

3. Click OK again to print a representation of the program.

To print from the Program Explorer

You can print an entire program or parts of a program from the Program Explorer.

1. To view the Program Explorer, click the Program Explorer button on the toolbar (or use View [image] Program Explorer).

2. Using the right mouse button, click on the context name in the Program Explorer that you want to print. You may need to expand the Program Explorer’s tree view to see all available names.

To print the entire program click on the program or file name at the top.

To print a single context in the program such as Main, a UserObject, or a UserFunction, click on the particular name.

3. In the context menu that appears, click on Print. The Print Options dialog box appears. The options are described above.

4. Set the options you prefer, then click OK.

5. The Print dialog box appears. Change the printing configuration if desired.

6. Click OK to print the program.

The following figure shows the Program Explorer with a context menu ready to print a UserObject.


To Print Objects in a VEE Program

You can print selected objects in a VEE program.

1. Select one or more objects in the program. Click on an object to select it. To select several objects, hold down the CTRL key while clicking on the objects or use your mouse to draw a rectangle around the objects while holding down the CTRL key.

2. Select File [image] Print Objects. The Print dialog box appears. Change the printing configuration if desired.

3. Click OK to print the selected objects.

Tip

You can also print objects programmatically by adding Print control inputs on those objects. This is useful for printing graphical XY display objects.


To Send Data to a Printer

You can send data from your VEE program directly to a printer.

1. Add a To Printer object to your program (I/O [image] To [image] Printer) and connect the data input pin to the source of the data that you want to print.

2. Double-click on the To Printer icon to display the open view containing the I/O transactions that output data.

3. The default output transaction is WRITE TEXT a EOL. If desired, change the transaction to output the data in some other form.

4. Run the program. When the To Printer object operates, the data is output to the printer, which prints the data using the current printing configuration.

Tip

The To Printer object outputs data through the Windows printer driver, which adds a header and changes the fonts. To output straight ASCII text to a printer from VEE for Windows, use the To File object with the file name set to LPT1 (or whichever printer port you are using).

See also

To Edit a File I/O Transaction

To Write Data to a File


To Plot a Graph

To Print a Graph

There is one way that you can print a graph from XY display objects such as the XY Plot or Waveform (Time) objects.

Select the Print command from the object menu of the XY display.


To Load an Instrument Driver

Agilent VEE supports instrument control through the use of instrument drivers and direct I/O. Instrument drivers include Panel Drivers (controlled through Panel Driver and Component Driver objects), VXIplug&play Drivers (controlled through Plug&play Driver objects), and IVI-COM Drivers (controlled through IVI-COM Driver objects). The Direct I/O object allows low-level transactions with an instrument.

Before you can use any instrument driver object, the appropriate instrument driver files must be installed. For the instrument drivers to communicate with instruments, you must also install the Agilent I/O Libraries.

Many Panel Drivers are provided with Agilent VEE. When you installed Agilent VEE, you could select the groups of drivers that you wanted to install. A few drivers are installed by default to run certain example programs. If you need to install additional drivers, run the VEE setup.exe program, and select the driver options that you need.

Note

VXIplug&play Drivers are available from instrument manufacturers who provide them. Agilent Technologies provides VXIplug&play Drivers for many Agilent instruments. From time to time, new and updated instrument driver files also become available. For your convenience, these files are available electronically from Agilent. See To Get Support and Download Instrument Drivers for directions to download files.


To add a TCP/IP Instrument

To Add USB or LAN Based Instrument

From version 8, to add a USB and LAN based instrument for VEE, you are not required to install Agilent's IO Libraries Suite unless you want to change the VISA alias for a USB instrument.

Agilent's IO Libraries Suite gives an alias, such as UsbDevice1, UsbDevice2, etc., to each instrument you connect via USB, because VISA addresses for USB devices are long and cumbersome. You can change these names by selecting the alias node in the explorer view and clicking the Change... button. Following figure shows how to set the alias in Agilent's IO Libraries Suite.

Refer to To Add an Instrument Configuration for detailed information on adding instrument configuration.


To Add an Instrument Configuration

It is easy to use an instrument control object once that instrument is listed in the Instrument Manager tool window.

To Automatically Add an Instrument

Instrument Manager provides a simple way to add and configure instruments. You can use this method when the instrument is connected to your computer and powered-on.

1. Select I/O [image] Instrument Manager… The Instrument Manager tool window appears displaying the current configuration in the Instrument List area.

2. Right click the root node of the instrument list to open the context menu and choose the Auto Discovery Settings command. The Auto Discovery Settings dialog appears.

3. Click the radio button for Detect, identify, and configure drivers... Then click OK.

4. Click on Find Instruments [image] toolbar button. Select the root node (My Configuration) or interface node if the Find Instruments [image] toolbar button is unavailable.

The Auto Discovery process displays its status as it runs. When Auto Discovery finishes, the current configuration is updated with an additional instrument entry named "newInstrument". This entry also shows the instrument’s VISA address. You can click Save [image] toolbar button now to save this configuration, or you can choose to edit some details of the new instrument entry. (Most people change the instrument name.) See To Edit an Instrument Configuration.

5. Click on the Save [image] toolbar button to save the new configuration.

To Manually Add an Instrument

1. Select I/O [image] Instrument Manager… The Instrument Manager tool window appears displaying the current configuration in the Instrument List area.

2. Click on Add instruments... . The Instrument Properties dialog box appears. This dialog box allows you to enter basic configuration information necessary for the new instrument.

3. Use the default Name or enter a unique new name.

4. To change the Interface, click on the interface name to display the list of supported interfaces. Click on the interface connected to your instrument.

5. In the Board Number box, type or select the Board Number.

6. In the VISA Alias box, type the visa alias. This VISA Alias must be the same as it is configured in Agilent IO library.

7. Click in the VISA Address field to set the instrument address. For information about determining what address to use for a particular instrument, refer to the owner's manual for the instrument.

Tips

Double clicking the example address in blue color under the VISA Address box can copy the example address to the VISA Address box.

8. Optional: To set additional device attributes, click on the Advanced... button. For information about the Advanced properties, see To Edit an Instrument Configuration. (The basic and advanced "Instrument Properties" dialogs work the same whether you are adding a new entry or editing an existing entry.)

9. Click on the Save [image] toolbar button to save the new configuration.

Notes

If you add or remove interface cards used on your system, you must update the I/O_config file by running the Agilent Connection Expert. Please see online help of the Agilent I/O Libraries Suite, for complete information about installing and configuring interfaces.

See Also

To Load an Instrument Driver

To Edit an Instrument Configuration

Instrument Manager

Owner’s manual for instrument


To Delete an Instrument Configuration

You can delete an instrument from the Instrument Manager tool window.

1. Select I/O [image] Instrument Manager.... Then select the instrument configuration name you want to delete by clicking on it.

2. Right click the instrument name, choose the Delete Instrument in the context menu. The selection is removed from the list.

3. Click on the Save toolbar button to save the new configuration.

Note

If you add or remove interface cards used on your system, you must update the I/O_config file by running the Agilent Connection Expert. Please see online help of the Agilent I/O Libraries Suite, for complete information about installing and configuring interfaces.

See Also

To Edit an Instrument Configuration

Instrument Manager


To Edit an Instrument Configuration

You can edit the configuration of any instrument in the current Instrument List.

1. Select I/O [image] Instrument Manager… The Instrument Manager tool window appears, displaying the current configuration in the Instrument List area.

2. Right-click the desired instrument in the Instrument List to open the context menu, and choose the Instrument Properties... This brings up the Instrument Properties dialog box. Various properties can be changed as described in the following sections.

To Edit Basic Instrument Properties

In the Instrument Properties dialog box, you can specify following basic properties:

Name: This can be any name you choose to help you identify the instrument. It is recommended that names start with a letter and not contain spaces.

Interface: Select the type of interface that is connected to the instrument.

VISA Alias: Enter the alias for the VISA address string.

VISA Address: Enter the VISA address of the instrument.

Board Number: Enter the board number for the interface board. The board number index starts at 0 and the default is 0.

Gateway: For local interfaces, select This host. For LAN-gatewayed interfaces, enter the hostname (or IP address) of the remote gateway.

1. In the Instrument Properties dialog box, click the desired field. Enter (or select) a new value. Modify other fields as needed.

2. Click on the Save button to close the dialog box and save the new configuration.

To Edit Advanced Instrument Properties

1. In the Instrument Properties dialog box, click on the Advanced... button. The Advanced Instrument Properties dialog box appears. This dialog box displays a variable set of tabbed sheets depending on the selected interface type. The following table shows tabs included in each interface type's Advanced Instrument Properties dialog box.

Tab Interface | General Driver | Direct I/O Driver | Plug&play Driver | IVI-COM Driver | Panel Driver | serial Driver | A16 Space Driver | A24/A32 Space Driver
GPIB | Yes | Yes | Yes | Yes | Yes | No | No | No
ASRL | Yes | Yes | No | No | Yes | Yes | No | No
TCP/IP | Yes | Yes | Yes | Yes | Yes | No | No | No
USB | Yes | Yes | Yes | Yes | Yes | No | No | No
NIDAQ | No Advanced Dialog box
VXI | Yes | Yes | Yes | Yes | Yes | No | Yes | Yes
GPIO | Yes | Yes | No | No | Yes | No | No | No

2. Click on the tabs and change the default settings as needed. To change settings, type new values in the fields or click on buttons to change their states. As a guideline, you should change the settings depending on the instrument and the type of instrument-control object you will use, such as a Panel Driver, Plug&play Driver, or Direct I/O.

To use an instrument driver, you must identify the driver file on the Panel Driver, IVI-COM or Plug&play Driver tabs. The driver file must exist on your hard disk.

For detailed information about the various configuration settings, click the Help button on the dialog box.

3. Click on the Save button to close the dialog box and save the new configuration.

Note

For NIDAQ interface, you can select Driver Type in it's Instrument Properties dialog box.

See Also

To Add an Instrument Configuration

Instrument Manager


Embedded I/O Configurations and Merging

VEE Pro can merge and import program elements from a program file that also contains an embedded I/O configuration. However, embedded I/O configurations themselves cannot be merged or imported. If the objects you are merging (importing) require configured instruments, you must augment the local I/O configuration to include those instruments.

One alternative is to add instruments to the current I/O configuration and save it with the "main" program. (In other words, the program file containing all the merged elements, or the program file that does the Import Library.) Another alternative is to ensure that all necessary instruments are contained in the I/O configuration file (vee.io) on the computer running the program.

VEE searches for the I/O configuration file as follows:

1. VEE always looks for the I/O configuration file in the location specified by the path to filename if you start Agilent VEE in command line using - vee.io path to filename. VEE creates an empty vee.io file in the path to filename if no vee.io file exists there.

2. If you do not start Agilent VEE in command line using - vee.io path to filename, which means you either start Agilent VEE from Windows, or start Agilent VEE in command line without using the -vee.io option. VEE will looks for the I/O configuration file in the location defined by the VEE Environment Variable if the VEE Environment Variable exists. VEE creates an empty vee.io file in the directory defined by the VEE Environment Variable if no vee.io file exists there.

3. If the VEE Environment Variable does not exist, then VEE looks for the I/O configuration file in the following default location.

%Appdata%\Agilent\ProductName\MajorVersionNumber + ".” + FirstDigitofProductMinorNumber

The %Appdata% is get from Environment.SpecialFolder.ApplicationData. For example, the default location of VEE Pro 8.5 in Windows XP / 2K / Vista is %Appdata% \Agilent\VEE Pro\8.5.

In addition, VEE copies the vee.io file from pre-version path to the default location in the first time launching of a VEE product.

VEE creates an empty vee.io file in the default location if no vee.io file exists there.

See Also

I/O Configuration Techniques


Dynamic I/O Automation Server

In previous versions of VEE, instrument bus addresses in the VEE I/O configuration file were static (fixed). In version 6.0, the Dynamic I/O Automation Server lets you find and identify instruments programmatically. This provides new levels of flexibility. For example, you can find all your instruments and then use Programmable Instrument Properties to set up Direct I/O objects.

Use

To use the Dynamic I/O Automation Server from VEE:

Select Device [image] ActiveX Automation References to display the ActiveX Automation References Dialog box. Then, check Agilent VEE DynamicIO 1.0 Type Library and click OK.

Select Device [image] Function & Object Browser to display the Function & Object Browser tool window. Select ActiveX Objects to display DYNAMICIOLib as the Library.

Examples

VEE examples are provided in the Help [image] Open Example… InstrumentIO directory.

See Also

Since this utility is a stand-alone ActiveX automation server, it can also be used from other applications, such as C++ and Visual Basic.


To Change Interface Dynamically

To Change VISA Interface and Address Dynamically

In Agilent VEE, each virtual instrument listed in the Instrument Manager associates with an unique VISA address and the instrument on that VISA address. If the VISA address is changed, then the virtual instrument will associate with another instrument on that new VISA address. All communications subsequent to the VISA address change between VEE and the virtual instrument will actually happen between VEE and the instrument on the new VISA address.

You can dynamically change an instrument's VISA address among GPIB, USB and TCP/IP interfaces or within the same interface. With this feature you can use an instrument via different interfaces easily.

To Change VISA Interface and Address Dynamically

You can use Formula box to change VISA interface and address.

For instance, there is an GPIB instrument named AGDMM, and you need to change its VISA address to USB0::2391::1031::US432109::0::INSTR, then in a Formula box you can write:

IO.AGDMM.VISAAddress = "USB0::2391::1031::US432109::0::INSTR";

Note

You can change a instrument's VISA address in the Instrument Manager Manually. In the Instrument Manager, right click the instrument you want to change the interface and address, and then choose the Properties.... The Instrument Properties dialog box appears. Change the VISA Address as you need, the Interface will change automatically next time you open this dialog box. Click OK to close the dialog box. Instrument list in the Instrument Manager will update automatically.

Some Scenarios to Dynamically Change VISA Interface and Address

1. To Communicate with Multiple instruments

With this feature you can easily talk to multiple instruments during runtime without configuring them manually in the Instrument Manager.

Example DynamicControlMultiInstruments.vee.

2. To Communicate with an instrument via different Interfaces

Without this feature, to communicate with instruments connected via different interfaces, you have to write separate code and do some configurations in the Instrument Manager for each interface.

With this feature, you can use the same piece of code for GPIB, USB and TCPIP interfaces. To communicate with an instrument via different interfaces, you only need to change the VISA address dynamically in a formula box and no configuration is needed in the Instrument Manager.

Example TestInstrumnetviaMultiInterfaces.vee.

Note

You can watch the dynamic changing of an instrument's VISA Address in Instrument Manager when you step through or pause a program. However, the VISA Address will change back to its design value, which is the VISA Address you configured manually in the Instrument Manager, when program stops.

See Also

Instrument Manager

See example Dynamicallychangevisaddress.vee.


To Read Data Using Direct I/O

This procedure shows how to use the direct I/O object to read data from an HP 34401A Multimeter.

1. Add a direct I/O object, configured for address 722, to the work area as shown in To Use a Direct I/O Object.

2. The direct I/O object uses transactions to communicate with an instrument. Double-click on the "blank" transaction (the highlighted field) in the object. The I/O Transaction dialog box appears with the variable a highlighted. Enter the string "MEAS:VOLT:DC?" (including quotation marks) in its place. Click on OK to create the transaction WRITE TEXT "MEAS:VOLT:DC?" EOL.

3. Select Add Trans from the object menu to add a second transaction, or double-click the next blank transaction. Change the transaction dialog box action to READ and the encoding to TEXT . Click on OK.

4. The direct I/O object now has two transactions:

a. WRITE TEXT "MEAS:VOLT:DC?" EOL writes the command string "MEAS:VOLT:DC?" to the instrument at address 722. To the HP 34401A Multimeter, the command string MEAS:VOLT:DC? means "output one dc voltage reading."

b. READ TEXT x REAL64 reads text data in the real format from the instrument at address 722, and outputs the data on the X data output terminal.

5. To complete the program, add an AlphaNumeric display object to the work area, and connect it as shown below. (You can run this program if you have an HP 34401A Multimeter connected to the GPIB at address 722.)

See Also

Direct I/O

MultiDevice Direct I/O

Lab3-3: Using Direct I/O

Help [image] Contents and Index [image] Tell Me About... I/O Transactions

Programming manual for your specific instrument


To Use a Direct I/O Object

To add a direct I/O object, use the Instrument Manager tool window. The HP 34401A Multimeter configuration is used as an example.

1. Select I/O [image] Instrument Manager.... The tool window appears with the list of configured instruments.

2. Click on the instrument you want to add to the work area. For an example click on dmm(hp34401a@(NOT LIVE)).

3. Click the Properties button; then, in the Instrument Properties dialog box, click the Advanced… button. In the Advanced Instrument Properties dialog box on the General tab, set Live Mode to ON. Click the OK buttons to return to the Instrument Manager.

4. Click the Direct I/O button. The outline of the direct I/O object appears. Place the outline where you want it in the work area, and click the mouse button. The object’s title bar contains the instrument’s configured name.

5. Double-click the transaction areas to enter commands for the instrument.

See Also

To Read Data Using Direct I/O

Direct I/O

MultiDevice Direct I/O

Lab3-3: Using Direct I/O


To Use a Plug&play Driver Object

To add a VXIplug&play Driver object to the work area, use the Instrument Manager tool window.

Note

You cannot use a VXIplug&play Driver object with any other instrument-control object (Panel Driver, Component Driver, or Direct I/O) to communicate with the same instrument in the same program.

1. Select I/O [image] Instrument Manager.... The tool window appears with the list of configured instruments.

2. Click on the instrument you want to add to the work area. If it is configured with a VXIplug&play driver, the Plug&play Driver button becomes active.

3. Click on the Plug&play Driver button and place the To/From VXIplug&play object in the work area.

4. Double-click on an empty transaction (or from the object menu select Add Trans or Insert Trans). The Select a Function Panel dialog box appears. It displays function panels grouped into logical categories. Categories will vary with each driver.

Click the [+] and [-] icons to expand and compress the hierarchical structure of folders and functions.

Click the [f(x)] icons to select the function panel you want to use.

5. Click OK on the Select a Function Panel dialog box. The Edit Function Panel dialog box appears.

6. Edit the settings on the Edit Function Panel for the values you need. Use the Help button for more information about the particular instrument driver.

7. Click OK. To set up another function for the instrument, double-click the next transaction in the To/From VXIplug&play object.

See Also

To/From VXIplug&play


Using NI Data Acquisition in VEE

Only one PXI bridge is supported at a time and its PCI bus number must fall between 0 and 9 inclusive.

There are six different National Instruments driver libraries supported in VEE: niDMM, niSCOPE, niDAQ, niDAQmx, niSWITCH, and niFGEN.

Library | Revision Number
NI-DAQ | 7.3 or later (tested up to rev. 7.4.1)
NI-DMM | 2.3.1 or later (tested up to rev. 2.5)
NI-SCOPE | 2.7 or later (tested up to rev. 3.0)
NI-FGEN | 2.2.1 or later (tested up to rev. 2.4)
NI-SWITCH | 2.3 or later (tested up to rev. 3.1)
NI-DAQmx | 8.1 or later

The instruments defined using these libraries are configured and discovered by the Instrument Manager just like any other supported instrument.

1 I/O [image] Instrument Manager

2 Select Add, enter a name for the instrument, and use the Interface drop down box to select “NIDAQ”.

3 Name the instrument and select the driver type from the drop-down list.

4 Assign an address for the instrument and set the Live Mode.

• for SCXI, addressing is SCXI{Cage #}::Slot Number

• for PXI, addressing is PXI{Cage #}::Slot Number

• for traditional NIDAQ, addressing is 1 through 64

Calls to the functions in these driver libraries are actually direct calls to the NI libraries you have installed on your computer as shown below.

NI help is available for all of the functions in each of the libraries. There are also a few higher-level Agilent functions that have been provided to simplify what are otherwise unnecessarily complex tasks using the NI function calls.

SCXI Support

Currently, only one SCXI card cage at a time is supported in a system, and its chassis number must fall between 1 and 5 inclusive, as set in NI-MAX.

There are 2 types of SCXI modules as far as VEE is concerned. These types are largely determined by how the SCXI card cage is connected to the system. After a ‘Find Instruments’ from the Instrument Manager, SCXI modules that show as NI-DAQ devices will use the NI-DAQ Driver. You will only be able to use the SCXI_xxxx transactions in this driver for these modules. Using any other transactions (like Analog In, Analog Out, Digital In, etc.) will cause:

SCXI modules that show as NI-SWITCH devices will use the NI-SWITCH Driver. Some SCXI modules will appear as both NI-DAQ and NI-SWITCH types. These modules have the option to be used as NI-DAQ devices and/or NI-SWITCH devices. You decide which driver to use based on the functionality you need.

NI-DAQ Asynchronousity Issues

Due to the fact that VEE cannot handle asynchronous transactions in To/From Plug&Play objects, we need to discourage the use of DAQ_Start(), SCAN_Start() and Lab_ISCAN_Start(). The equivalent functionality can be done synchronously with their counterpart transactions DAQ_Op(), SCAN_Op() and Lab_ISCAN_Op(), respectively. In the case of Lab_ISCAN_Op() and SCAN_Op(), additional setup and configuration transactions, like SCAN_Setup(), will have to precede the XXX_Op() transaction.

Tested Instruments

The following instrumentation has been physically tested to function with VEE:

  • PXI-5411 Arbitrary Waveform Generator (NI-FGEN)

  • PXI-5112 100MHz Digital Oscilloscope (NI-SCOPE)

  • PXI-2503 Relay Multiplexor (NI-SWITCH)

  • NI-4050 PCMCIA 5 ½ Digit DMM (NI-DMM)

  • PXI-4060 5 ½ Digit Multimeter (NI-DMM)

  • PXI-4070 6 ½ Digit FlexDMM (NI-DMM)

  • PXI-6025E Multifunction I/O (NI-DAQ)

  • PCI-MIO-16XE-10 Multifunction I/O (NI-DAQ)

  • PCI-6503 Digital I/O (NI-DAQ)

  • NI SCXI-1100 32-chan +-10V Analog Input Module (NI-DAQ)

  • NI SCXI-1163 32-chan Digital Output Module (NI-DAQ)

  • NI SCXI-1161 Relay Module (NI-DAQ)

  • NI SCXI-1161 Relay Module (NI-DAQmx)

  • PCI-MIO-16XE-10 Multifunction I/O (NI-DAQmx)

  • PXI-2503 Relay Multiplexor (NI-DAQmx)

  • PXI-6025E Multifunction I/O (NI-DAQmx)

  • PCI-6503 Digital I/O (NI-DAQmx)

Note that some equipments show up multiple times because they can be talked to by VEE with more than one drivers.

NOTE

Some newer PXI/CompactPCI cards will NOT be useable in VEE unless National Instruments VISA is installed as the primary VISA.

  • Remove NI VISA, including the dependent products like NI-DMM, NI-SCOPE, NI-FGEN, NI-SWITCH, etc.

  • Reinstall NI VISA, NI-DMM, NISCOPE, NI-FGEN, NI-SWITCH, etc. The installer will complain that Agilent VISA is already installed. Continue with the installation and the Agilent VISA DLL will be renamed to visa32.Agilent Technologies.dll.

See Also

To/From NIDAQ, NI-FGEN, NI-SCOPE Fetch/Read Functions, NI-DAQmx


IVI-COM and the Instrument Manager

IVI is a new instrument driver standard being developed by the IVI Foundation. The IVI Foundation is a consortium established to promote specifications for programming test instruments. These specifications provide multiple benefits but primarily make instrument interchangeability simpler. For a review of the IVI Foundation, go to http://www.ivifoundation.org/.

The strength of the IVI standards is instrument interchangeability. Assume two vendors provide IVI-COM drivers for their DMMs. To meet the IVI standard, the base class drivers must be interchangeable. This means that whichever driver you use on your system, the DMMs from either vendor will work. Your code is reusable without any intervention.

There are four scenarios for IVI-COM driver use. In all cases you must first download and install the IVI drivers for the instrument you are going to use. Then apply one of the following four scenarios:

1 Use this scenario when instrument interchangeability is not important and using a device driver is sufficient.

Start the Instrument Manager and add an instrument. Double-click the instrument to get to its properties page and select Advanced. Select the IVI-COM Driver tab and choose the IVI driver name that matches your instrument. You have now set up an instrument specific driver for your instrument. An instrument specific device driver has manufacturer functions that make it unique from other instrument drivers in the same class.

At this point, you can go back to the Instrument Manager, select the instrument, and choose the IVI-COM Driver button to create a To/From transaction object.

2 Use this scenario if instrument interchangeability is important and using a device driver is sufficient.

Start the Instrument Manager and add an instrument. Double-click the instrument to get to its properties page and select Advanced. Select the IVI-COM Driver tab and choose the IVI driver name that matches your instrument. In the box labeled Instrument Interchangeability, check the checkbox labeled Use Class Compliant Interface. Checking this box tells VEE that you want VEE to talk to the instrument using only the class compliant interface of the instrument driver. This makes the instrument interchangeable with other instruments of that class, such as DMM or Scope.

3 Use this scenario when instrument interchangeability is not important and using an IVI session name is important.

Start the Instrument Manager and add an instrument. Double-click the instrument to get to its properties page and select Advanced. Select the IVI-COM Driver tab and choose the IVI session name that matches your instrument. The IVI session name will gather the instrument’s configuration information from the IVI Config Store, so the resource string will be grayed out.

If you do not have a session defined, go to the Instrument Interchangeability box and select the button labeled Configure IVI Driver Session. Do not check the Use Class Compliant Interface checkbox. The application that appears is used to manage your IVI Config Store information. The icon on the top left finds instruments that are directly connected to your computer and reads others that are identified in the IVI Config Store.

Once the instruments have been found, right click on the one you want to add a session for and choose Add Instrument Session. You must have an IVI driver installed on your computer before running this wizard. When the wizard finishes, you can choose the session name you just created.

You are using an instrument specific driver with a IVI session name.

4 Use this scenario if both instrument interchangeability and using an IVI session name are important.

Start the Instrument Manager and add an instrument. Double-click the instrument to get to its properties page and select Advanced. Select the IVI-COM Driver tab and choose the IVI session name that matches your instrument.

If you do not have a session defined, go to the Instrument Interchangeability box and select the button labeled Configure IVI Driver Session. In any case, check the Use Class Compliant Interface checkbox.

The application that appears is used to manage your IVI Config Store information. The icon on the top left finds instruments that are directly connected to your computer and reads others that are identified in the IVI Config Store.

Once the instruments have been found, right click on the one you want to add a session for and choose Add Instrument Session. You must have an IVI driver installed on your computer before running this wizard. When the wizard finishes, you can choose the session name you just created.

You are using a class compliant driver with a IVI session name.

See Also

.NET and IVI Drivers, IVI Driver Example


To Use a Panel Driver Object

To add a Panel Driver object to the work area, use the Instrument Manager tool window. The HP 34401A Multimeter configuration is used as an example.

1. Select I/O [image] Instrument Manager.... The tool window appears with the list of configured instruments in the Instrument List area.

2. Click on the instrument you want to add to the work area. If it is configured with an instrument driver file, the Panel Driver button in the Create I/O Object area becomes active. For an example click on dmm(hp34401a@(NOT LIVE)).

3. Click the Panel Driver button. The outline of the instrument panel object appears. Place the outline where you want it in the work area, and click the mouse button.

4. With live mode OFF (default), the hp34401a instrument panel generates simulated data. Try clicking on the ? in the display field. A simulated reading appears. Live mode is available only in Panel Drivers.

With live mode OFF, you can run your I/O program even if an instrument is not present. Once you've tested the program and connected an instrument, you can set live mode to ON.

5. The Measure Panel is shown by default, which allows you to select the Function, Range, and so forth. To change the Function setting, click on the Function button labeled DC Volts.

6. To change the function to DC Amps, double-click on DC Amps in the list. To change back to DC Volts, click on the Function button, now labeled DC Amps, and then double-click on DC Volts in the list.

While live mode is OFF, none of these changes affect an instrument, even if one is connected to your system. However, if live mode is ON and you have an HP 34401A Multimeter connected to the GPIB (correctly addressed and configured), the changes on the VEE instrument panel object will automatically change the state of the instrument.

7. The Measure Panel is only one of several panels that you can select. Click on the Measure Panel button at the upper-right corner of the object.

8. Double-click on Status Panel in the list. The Status Panel appears.

9. To go back to the Measure Panel, click on the Status Panel button and double-click on Measure Panel.

The various panels in an instrument panel object let you control almost all functions of an instrument. However, you need to be familiar with a particular instrument in order to use the instrument panel effectively. Refer to the instrument owner's manual for further information. For information about an instrument panel object, select Help from the object menu.

See Also

To Read Data with a Panel Driver Object


To Read Data with a Panel Driver Object

In this procedure, you will create a simple program that displays simulated voltage readings from an instrument panel object for an HP 34401A Multimeter.

1. Add an instrument panel object for the HP 34401A (I/O [image] Instrument Manager...).

2. Select Add Terminal by Component [image] Select Output Component from the object menu of the instrument panel.

3. Click on the HP 34401A display. The Reading terminal is added to the output.

4. Add an AlphaNumeric display object to the work area, connect it as shown below, and run the program. Since live mode is OFF, the data is simulated, which is indicated by the Simulated Data label (and by (NOT LIVE) in the title bar).

5. To turn live mode ON, select I/O [image] Instrument Manager..., select dmm (hp34401a @ (NOT LIVE)) in the list (if it is not already highlighted), and then click on Properties. The Instrument Properties dialog box appears showing the configuration for the HP 34401A Multimeter.

6. If the address shown (the default is 722) doesn't match the address of the instrument, enter the correct address. (For information on addressing a particular instrument, refer to the instrument owner's manual.)

7. Click the Advanced… button. Click the button to the right of Live Mode. The button toggles from OFF to ON. Then click the OK buttons to return to the Instrument Manager dialog box.

8. Click the Save button. The instrument panel now has live mode ON.

The new title, hp34401a (@ 722), shows that live mode is ON and that the instrument panel is configured to communicate with an HP 34401A Multimeter at GPIB address 722. Of course, the program will time out unless there actually is an HP 34401A at address 722 connected to your computer.

At this point, if you have an HP 34401A Multimeter, you can connect it and run the program. Otherwise, use the Advanced Instrument Properties dialog box (I/O [image] Instrument Manager..., click on Properties, click on Advanced…) to return to live mode OFF.


To Use a Component Driver Object

You can gain a slight increase in performance by using a component driver object. The HP 34401A Multimeter configuration is used as an example.

1. Select I/O [image] Instrument Manager.... The tool window appears with the list of configured instruments in the Instrument List area.

2. Click on the instrument you want to add to the work area. If it is configured with an instrument driver file, the Component Driver button in the Create I/O Object area becomes active. For an example click on dmm(hp34401a@(NOT LIVE)).

3. Click the Component Driver button, and place the object outline in the work area.

4. The component driver object appears as an icon. Double-click on the icon to display the open view.

5. Add a Reading terminal to the component driver object (object menu [image] Add Terminal [image] Data Output).

See Also

manual22.vee in the manual examples directory
Help [image] Open Example...

Component Driver


Selected Techniques

This section describes some techniques for using Panel Driver and Component Driver objects interactively or in a program.

Using Panel Driver Objects Interactively

The open view of a Panel Driver object provides a graphical control panel that you can use to interactively construct a measurement state. If you connect the corresponding physical instrument to your computer and turn Live Mode on, you can control the physical instrument interactively as you build the measurement state.

To change an individual setting, click the corresponding field in the graphical control panel and complete the resulting dialog box. To make a measurement and view the result, click the display region of a numeric or XY display. XY displays may take a few seconds to update.

Using Panel Driver Objects Programmatically

To add a Panel Driver object to your program:

1 Click I/O [image] Instrument Manager.... The Instrument Manager tool window appears.

2 Click the desired instrument to highlight it and then click the Panel Driver button.

note

The Panel Driver button is inactive ("grayed out") if the instrument has not been configured with a Panel Driver file. See for configuration procedures.

3 When the object outline appears, position the cursor and click once to place the object in the work area.

To use Panel Driver objects in a program, you will often use input or output terminals to set the values of components. Each input or output terminal actually corresponds to a component in the driver. There are two ways to add a terminal:

• Select Add Terminal [image] Data Input or Add Terminal [image] Data Output from the Panel Driver object menu. A list box appears that lists all the valid driver components not yet used as terminals. Double-click the component in the list that you wish to add as a terminal.

• Select Add Terminal by Component [image] Select Input Component or Add Terminal by Component Select Output Component from the Panel Driver object menu. After making this selection, click one of the fields or display areas in the graphical control panel to add the corresponding component as a terminal.

In general, it is more convenient to use the first method listed above because you do not need to guess the name of the component you want to use. However, some components are not visible on any part of the graphical control panel. You must access these using the second method.

Using Component Driver Objects in a Program

To add a Component Driver object to a program:

1 Click I/O [image] Instrument Manager.... A list of configured instruments appears.

2 Click the desired instrument to highlight it and then click the Component Driver button.

note

The Component Driver button will be inactive ("grayed out") if the instrument has not been configured with a Panel Driver file. See for configuration procedures.

3 When the object outline appears, position the pointer and click once to place the object in the work area.

Component Driver objects are generally used when you need to repeatedly execute an instrument control object while changing only a few components. Component Driver objects are preferred over Panel Driver objects in these situations because Component Driver objects write and read only the components you specify and execute somewhat faster.

Following program illustrates this type of situation. This program measures the frequency response of a filter by sweeping the input frequency sourced by fgen and measuring the response using dvm. Since the subthread attached to For Log Range executes repeatedly, component drivers are used to improve execution speed. Note that Panel Driver objects are still appropriate for the initial set up of fgen and dvm.

The above program is stored in the file manual15.vee in the examples directory.

Getting Panel Driver Help

To obtain help about an Panel Driver, select Help from the object menu of a Panel Driver or Component Driver object. Then, open the appropriate help topic from the resulting dialog box.

See Also

How Panel Driver-Based I/O Works, Inside Panel Drivers, Panel Driver Operation


Using PC Plug-in Boards

VEE provides two ways to control PC plug-in boards or cards:

1 Data Translation's Visual Programming Interface. (Order the VPI application directly through Data Translation.)

2 Dynamic link libraries supplied by the PC board manufacturer, such as ComputerBoards or Meilhaus. (See Using Dynamic Link Libraries for information on using dynamic link libraries.)

Data Translation's Visual Programming Interface (VPI)

Data Translation's VPI works with VEE to create seamless data acquisition performance for PC plug-ins. By leveraging the flexibility of Data Translation's Open Layers standards, you have access to over 50 data acquisition boards.

The VPI works directly with plug-in ISA, PCI, and USB-based data acquisition cards that require low channel count. The VPI adds a menu selection and specific PC plug-in data acquisition icons to VEE. These drive the Data Translation hardware functionality.

Amplicon

Amplicon has a wide range of analog and digital I/O PC plug-in boards within the 200 Series, all with VEE support.

The software interface is part of Amplicon’s AmpDIO driver package, a 32-bit API with a multithreaded DLL for Windows and support for interrupt driven acquisition. The API contains over 100 calls for efficient and flexible programming as a Compiled Function using a VEE-specific definition file and the facility to utilize up to eight boards in one program.

In addition to Amplicon’s own range of plug-in boards, which includes serial communication devices, Amplicon can supply boards from a wide range of other manufacturers for data acquisition, serial communication, and GPIB applications.

Following figure shows the VEE runtime software (provided free with Amplicon analog output boards PCI224 and PCI234 and analog input boards PCI230 and PCI260) providing concurrent input and output signals on a PC.

ComputerBoards PC Plug-ins

ComputerBoards offers low cost, powerful PC plug-in boards that are compatible with VEE. (For a complete list of supported PC plug-in vendors, see VEE literature.)

You simply install the board and its I/O library, and configure the board using a program supplied by the manufacturer. Follow the instructions to connect the board to the device. In VEE, import the library, and you are ready to call the measurement functions in the ComputerBoards I/O library. See the figures below from a demonstration program supplied by the manufacturer.

Above figure shows the panel view of the demonstration program using this 100 KHz A/D board. Following figure shows VEE importing the ComputerBoards I/O library that made these data acquisition function calls possible.

Meilhaus Electronic ME-DriverSystem

Meilhaus Electronic is one of the leading European designers, producers and sales companies for PC-based data acquisition and interface technology. The ME-DriverSystem for Windows on CD-ROM is included with all data acquisition boards made by Meilhaus Electronic (i.e. ME series). The ME-DriverSystem is also integrated into the VEE menu structure.

After the ME-DriverSystem for VEE is installed, the driver functions appear in a VEE pull-down menu.

The second menu level presents functional groups such as Analog Input and Output, Digital I/O, and special functions of certain boards. Following figure shows the user panel for data acquisition board ME-3000.

Finally, in the third menu, the actual functions are located, such as me3000AISingle.


To Poll GPIB Instruments

From time to time a GPIB instrument sends a service request ("SRQ") on the bus. Agilent VEE provides two devices that help you determine what device has requested service, and what the problem is. Both of these objects are found under I/O [image] Advanced I/O.

The Interface Event object reports an event for the entire bus. For example, if Interface Event is set to report an SRQ for hpib7, any device on the interface at logical unit 7 can cause an event. You can also use the Interface Event object to detect events on the serial and VXI interfaces, if such instruments are configured.

The Instrument Event object returns the status byte from a particular instrument. On the GPIB, use Instrument Event objects to poll the individual devices on the bus.

Example

The following program shows how to use the Interface Event and Instrument Event objects to process GPIB service requests:

In the program the Interface Event object waits for an event on hpib7, that is, on the GPIB interface at logical unit 7. However, the Interface Event object does not indicate which device on the bus caused the event.

The event output of the Interface Event object activates both of the Instrument Event objects, which individually poll two GPIB instruments (the HP 34401A and HP 54600A). Each Instrument Event object has its action set to Any Set and its mask set to #H10. Any Set causes the object to wait for an event to occur, and then perform a logical AND of the returned value with the mask #H10, which corresponds to bit 4 in the status byte (DAV, or "data available"). The result is returned on the status output terminal.

See Also

Instrument Event

Interface Event


To Monitor Bus Messages

Agilent VEE communicates with an instrument by means of a series of messages. On the GPIB, the bus messages follow the IEEE-488 standard. Normally, these messages are not seen. However, when you debug your I/O program you may want to monitor the messages on the bus. To do this, open the Agilent IO Monitor under IO Menu. You can also use this IO monitor to monitor VXI or serial interface messages.

Note

The Agilent IO Monitor does not show any I/O done from VXIplug&play drivers.

To launch Agilent I/O Monitor

Select I/O [image] I/O Monitor. The Agilent IO Monitor appears.

To monitor the messages on the bus, click the Start [image] button to start a monitoring session, then run your VEE program. Agilent IO Monitor will display all messages on bus.

For more information about using Agilent IO Monitor, refer to the help of Agilent IO Monitor.

See Also

Agilent IO Monitor


To Enter a Number

You can enter a number in any VEE numeric-entry field using the conventions shown in the following examples. The hyphen (-) is used as a minus sign and the period (.) is used as a decimal point. You can include a plus sign (+) in a numeric entry field if desired. Notice that the comma (,) is not allowed as a separator. (Text-entry fields accept any arbitrary string of characters.)

Ordinary numeric entry

1001

1020768 (But not 1,020,768)

12.12

-1.223

Exponential numeric entry

1.23E3 (Equivalent to 1.23x10^3 or 1230)

6.0225E23 (Equivalent to 6.0225x10^23)

6.6256E-27 (Equivalent to 6.6256x10^-27)

Numeric entry using the ISO abbreviations

1.23k (Equivalent to 1.23x10^3 or 1230)

3.61M (Equivalent to 3.61x10^6)

2.3n (Equivalent to 2.3x10^-9)

The following table lists the ISO abbreviations recognized by VEE for entering a number.

Abbreviation Suffix Multiple

X exa 10^18

P peta 10^15

T tera 10^12

G giga 10^9

M mega 10^6

k or K kilo 10^3

m milli 10^-3

u micro 10^-6

n nano 10^-9

p pico 10^-12

f femto 10^-15

a atto 10^-18

VEE may change the form of the number you enter to another, equivalent form. For example:

+1.23 becomes 1.23 (plus signs are dropped)

6.3E-9 becomes 6.3n

6.0225E23 becomes 602.25E21 (in the standard number format)

See also

To Change the Number Format


To Change the Number Format

You can change the default global number format that VEE uses for all objects that display numbers, and you can change the number format for certain individual objects that display numbers.

To Change the Global Number Format

1. Select Default Preferences from the File menu. Then select the Number tab in the dialog box.

2. Select the desired number format by changing the appropriate fields:

a. Integer determines the number base for integers: Decimal, Octal, Hexadecimal, or Binary. (Click on the field or its arrow for the drop-down list.)

b. Real determines the format of real numbers: Standard, Fixed, Scientific, or Engineering. (Click on the field or its arrow for the drop-down list.)

c. Significant digits determines the number of significant figures (limit is 18). Type in the desired number.

3. Choose how you want to save your changes:

a. Click on Save to save the changes as new defaults in vee.rc.

b. Click on OK to use the changes for this VEE session only (until you select File [image] New, Open, or Exit).

To Change the Number Format for Certain Objects

You can select a number format independently for the following objects. The selected number format overrides the global number format, but only for the particular object.

Numeric sliders and knobs on menu Data [image] Continuous

Constants on menu Data [image] Constant

AlphaNumeric on menu Display

Logging AlphaNumeric on menu Display

Fill Bar, Meter, Tank, and Thermometer on menu Display [image] Indicator

XY graphical displays on menu Display

1. Select Properties from the object menu of the object, then click on the Number Format.

2. Click on the checkbox to turn off Global Format. Then, click on the number format field (or its arrow) to show the drop-down menu.

3. Select the number format you want the object to use, then click on OK.


To Change the Trig Mode

In VEE, trigonometric values may be entered and displayed in degrees, radians, or gradians, depending on the trig mode.

The new trig mode you choose is active for the duration of the current VEE session. When you restart VEE, the trig mode reverts to the default (Degrees). Each context (Main, UserObject, and UserFunction) has its own trig mode setting.

1. Open the object menu for the Main, UserObject, or UserFunction Window, then choose Properties.

2. Select Trig Mode and choose (Degrees, Radians, or Gradians).

Note

All internal calculations are done in radians. You'll get slightly faster performance if you set the trig mode to Radians because VEE won't need to make the conversion to radians and back.

Shortcut

Double-click the Main, UserObject, or UserFunction Window’s title bar to access the Properties dialog box.


To Use a Data Constant

VEE provides several types of data constants. To use a scalar data constant:

1. Select a data constant object (Data [image] Constant [image]). The choices are Text, UInt8, UInt16, Int16, Int32, Int64, Real32, Real64, Coord, Complex, PComplex, Date/Time, and Record.

2. Enter the appropriate type of data in the constant object. The most common types are the Text, Int32, and Real64 constant objects:

a. In the Text constant, you can enter any text string (the maximum length is 32,767 characters).

b. In the Int32 constant, you can enter any 32-bit, two's-complement integer (the range is -2147483648 through +2147483647).

c. In the Real64 constant, you can enter any 64-bit real number (the range is ±1.7976931348623157E308).

In the example below, the Text, Int32, and Real64 constant objects are connected into VEE program threads. Data types are automatically converted as needed by the object receiving the data. In this example, the integer 3 is converted to a real, and added to 6.24 resulting in the real value, 9.24.

See also

To Create an Array Constant

To Use a Data Slider

To Use a Data-Selection Object

To Use a Data Input Dialog Box

Converting Data Types on Input Terminals


To Use a Data Slider

To Use a Data Slider and Knob

VEE provides four types of data slider and knob objects: the Real64 Slider, Int32 Slider, Real64 Knob and Int32 Knob. These objects allow you to input a value in your program by moving a linear slider or circular knob.

To use a Real64 Slider or Int32 Slider

1. Select Data [image] Continuous [image] Real64 Slider or Int32 Slider, and place the object in the work area. By default the Real64 Slider object has a range of 0 through 1; the Int32 Slider range is 0 through 100.

2. Change the current value (displayed in the field at the top) using any of three ways:

a. Click and hold on the slider knob while moving it up or down.

b. Click on the spin-field arrows beside the value.

c. Click on the value and type a new one.

3. To change the range, click on the upper or lower limit field and type in the value.

To use a Real64 Knob or Int32 Knob

1. Select Data [image] Continuous [image] Real64 Knob or Int32 Knob, and place the object in the work area. By default the Real64 Knob object has a range of 0 through 1; the Int32 Knob range is 0 through 100.

2. Change the current value (displayed in the field at the bottom) using any of three ways:

a. Click and hold on the circular knob while turning it around.

b. Click on the spin-field arrows beside the value.

c. Click on the value and type a new one.

3. To change the range, click on the upper or lower limit field and type in the value.

See also

Int32 Knob

Int32 Slider

Real64 Knob

Real64 Slider


To Use a Data-Selection Object

VEE provides six types of data-selection objects: Radio Buttons, Cyclic Button, List, Drop-Down List, Pop-Up List, and Slider List.

To use a data-selection object

(This procedure describes the Radio Buttons object, and applies to all six types of data-selection objects.)

1. Select Data [image] Selection Control [image] Radio Buttons and place the object in the work area. Note that the default radio button selections are Item 1, Item 2, and Item 3.

2. To change the default selections, select Edit Enum Values from the object menu. The Edit Enum Values dialog box appears.

3. Edit the values as needed. Use Tab (or down-arrow) to advance, Shift+Tab (or up-arrow) to back up among the fields. You can replace the text in each field or, to add fields, tab past the last field and type in additional text.

4. When you are finished editing the fields, click on OK.

To change a data-selection object type

1. Select Properties from the object menu. The Selection Control Properties dialog box appears.

2. On the General tab, click on the Format type you prefer, then click on OK.

See also

Selection Control


To Use a Data Input Dialog Box

Three of the built-in dialog box objects under Data [image] Dialog Box let you prompt for data input in a program. They are Text Input, Int32 Input, and Real64 Input.

(This procedure describes a Real64 Input dialog box object, and applies similarly to the Int32 Input and Text Input objects.)

1. Add a Real64 Input dialog box object to the work area (Data [image] Dialog Box [image] Real64 Input).

When the Real64 Input object operates, it displays a pop-up dialog box requesting a real number from the user. You can set the following parameters:

a. Prompt/Label determines the message displayed in the dialog box.

b. Default Value determines the optional default value to be displayed in the dialog box.

c. Value Constraint determines the range or other test that the value entered must match.

d. Error Message determines the error message to be displayed if the user responds with data that fails the test in Value Constraint.

2. Change the Prompt/Label field to Please enter a real value.

3. Run the program. The pop-up dialog box appears.

4. Enter 11 in the dialog box and click on OK. An error message appears.

5. Click on OK in the error message box. Now enter a number in the range 0 through 10 in the Real64 Input dialog box, and click on OK. The number is accepted and output on the Value terminal.

See also

Dialog Box

About Built-In Dialog Box Objects


To Enter a Formula

The basic mathematical object in VEE is the Formula object:

When placed in the work area, the object contains a preset expression and has one data input terminal, A. Note that variable A in the expression corresponds to data input terminal A.

Each variable in an expression is replaced by data on the input terminal with the same name as the variable. Variable names and terminal names are not case-dependent. In the expression a+1, the variable a corresponds to terminal A.

A variable in an expression must have a corresponding input terminal, or an error results. If you use a global variable, no corresponding terminal is required.

To use the Formula object

1. Add the Formula object to the work area (Device [image] Formula).

2. Click on the expression field in the Formula object and modify the expression as desired. For example, enter the expression 2*A+abs(B)+sin(C)+6. You can enter one or more expressions on multiple lines by pressing Enter.

3. Add data input terminals as required. (Place the pointer in the data input terminal area and press Ctrl+A.) Delete any unused data input terminals. (Place the pointer over the terminal and press Ctrl+D.)

4. Connect all of the data input terminals to appropriate sources of data, and the Result data output terminal to a display object, to complete your program.

Beginning with VEE 8.0, Code Completion and Code Insight are available in Formula.

Example

The following program uses the Formula object to evaluate an expression and display the result: Notice that the expression is split between terms across multiple lines.

See also

To Create a Variable

Formula

Processing Data

Code Completion

Code Insight


To Use the Math Operators and Functions

Over 150 built-in mathematical objects are provided with VEE in the form of operators and functions. These are really Formula objects that have been pre-configured with a descriptive title, an expression, and the appropriate data input terminals. To access the operators and functions use the Device [image] Function & Object Browser or the toolbar button.

Function & Object Browser button

You can modify the math objects as follows:

1. Change the expression to any valid VEE expression.

2. Change the title to describe the new expression.

3. Add or delete data input terminals as required.

Tips

1. Don't use several formula objects to "wire" an expression. Instead, combine the mathematical operators and functions into a single expression in a single object. VEE programs run faster when fewer objects are used.

Don't do this:

Do this instead:

2. When changing the expression, be sure to have corresponding input terminals for variable names.

3. When changing the names of the data input terminals (just double-click on the terminal and type in a new name), be sure you change the corresponding variable names in the expression as well.

4. Before minimizing the object to its icon, be sure to change the title to describe what the new mathematical expression does. It is good programming practice to change object titles all the time.

See also

Processing Data


To Use Mixed Data Types in an Expression

VEE automatically converts data types as needed, so you can use expressions containing mixed data types. Just enter the expression in a mathematical object and connect the data sources to the appropriate data input terminals.

Example

In the following program, the Formula object receives waveform data on input terminal A and real data on input terminal B. The Formula object evaluates the expression abs(A)+B by adding the real value 0.75 to the absolute value of each of the 256 points in the waveform.

See also

Processing Data


To Use an Expression in an If/Then/Else Object

VEE can evaluate mathematical expressions and branch program flow according to the result. The basic conditional object is the If/Then/Else object.

You can change the default expression in the If/Then/Else object to any conditional expression, or use the objects found under Flow [image] Conditional. The Conditional objects are really If/Then/Else objects pre-configured with expressions, descriptive titles, and data input terminals.

To use the If/Then/Else object

1. Add the If/Then/Else object to the work area (Flow [image] If/Then/Else).

2. Click on the expression field in the If/Then/Else object and modify the expression as desired. For example, enter the expression A==B OR B>=C.

3. Add data input terminals as required. (Place the pointer in the data input terminal area and press Ctrl+A.) Delete any unused data input terminals. (Place the pointer over the terminal and press Ctrl+D.)

4. Connect all of the data input terminals and one or both of the data output terminals to complete your program. If the expression is "true," the result of the expression (generally a 1) is output on the Then terminal. If the expression is "false" a 0 is output on the Else terminal.

5. If desired, add Else If conditions to the object.

Example

In the following program, if the expression A==B OR B*C==50 is true, the Then output terminal activates UserObject1. If the expression is false, the Else output terminal activates UserObject2.

See also

To Branch within a VEE Program

Conditional

If/Then/Else

Processing Data


To Use an Expression in a Transaction

VEE mathematical expressions can be evaluated and used in I/O transaction objects, such as the To File and From File objects.

Example of evaluating an expression in a To File transaction

1. Add a To File object to the work area (I/O [image] To [image] File).

2. Double-click on the transaction WRITE TEXT a EOL. The I/O Transaction dialog box appears.

3. Click on the default expression, a, and change the expression to a+sin(b):

4. Click on OK to save the new transaction (WRITE TEXT a+sin(b) EOL).

5. Add a B data input terminal to the object, and connect the data input terminals.

In the following program, the To File object adds the value of a (1) to the value of sin(b) (the sine of 30 degrees is 0.5), and outputs the result 1.5 to the file named myFile.

See also

Formula, From File, To File

Processing Data


To Find the Length of a String

1. Add the strLen(str) object to the work area using the Function & Object Browser - on the toolbar, click on

2. Connect the source of string data to the str data input terminal. Connect the Result output as desired.

3. Run the program. When the strLen(str) object operates, the length of the string is output on the Result terminal.

Examples

The strLen(str) object outputs the length of the string in bytes as an Int32 number. If str is a one-dimensional string array, strLen(str) returns an array which contains the length of each element of the array:

See also

strLen(str)


To Obtain a Substring

Two functions let you obtain a substring:

strFromThru(str,from,thru)
strFromLen(str,from,len)

Where:

str is the original string.

from is the position where the substring starts.

thru is the position where the substring stops.

len is the length of the substring.

All character positions in a string are zero-based. That is, the first character is at position 0.

To obtain a substring using strFromThru(str,from,thru)

1. Add the strFromThru object to the work area using the Function & Object Browser.

On the toolbar, click on [image] then look under
Built-in Functions
String
strFromThru

2. Connect the source of string data to the str input terminal.

3. Specify the from and thru values:

a. Connect data to the from and thru input terminals,

or

b. Change the expression to explicitly specify from and thru. For example, the expression strFromThru(str,0,5) returns characters 0 through 5 (the first six characters) of string str. Remember to delete the from and thru terminals if you do this.

Example

The following program returns the first six characters of the string:

See also

strFromLen (str,from,len)

strFromThru (str,from, thru)


To Concatenate Strings

You can use addition (+) and multiplication (*) in VEE to concatenate strings.

Examples

You can concatenate two strings:

You can concatenate a string and a number (the number is converted to a string):

You can multiply a number and a string to repeatedly concatenate the string:

See also

Accumulator

Concatenator


To Compare Two Strings for Equality

Example

The following program compares two strings for equality using a conditional object. If the two strings are exactly the same (including spaces), the result of the expression (in this case, a 1) is output on the Then terminal. Otherwise, a 0 is output on the Else terminal. This comparison is case-sensitive (Now is not equivalent to now).

See also

Conditional

strPosStr (str1,str2)


To Convert a Number into a String

You can convert a number into a string using To String. The following procedure shows how to convert the current time in seconds into a string in the time stamp format:

1. Add a To String object to the work area (I/O [image] To [image] String). Double-click on the icon to show the open view object.

2. Double-click on the default transaction WRITE TEXT a EOL. The I/O Transaction dialog box appears.

3. Click on DEFAULT FORMAT (or its arrow) to show the drop down menu. Select TIME STAMP FORMAT and click on OK.

4. Add a now()object using the Function & Object Browser.

On the toolbar, click on [image] then look under
Built-in Functions => Time & Date => now

Connect the now() to the data input terminal and an AlphaNumeric display to the data output terminal of To String.

5. Run the program. The now() object outputs the time in seconds. This value is converted to the time stamp format and displayed.

See also

intToChar(a)

To String

Help =>Contents and Index => Tell Me About... => I/O Transaction


To Convert a String into a Number

If a string includes numeric information that can be read as a number, you can use From String to extract the number.

1. Add a From String object to the work area (I/O [image] From [image] String). Double-click on the icon to obtain the open view object. The default transaction is READ TEXT x REAL64, which reads the string as text and outputs a real number if possible.

2. To view the results, connect a Text constant object to the data input terminal, and an AlphaNumeric display to the data output terminal.

3. Enter the string Item number: A1222 in the Text constant and run the program. The real number value 1222 is output to the display.

See also

charToInt(a)

From String

Help =>Contents and Index => Tell Me About... => I/O Transaction


To Create an Array Constant

You can create one-dimensional arrays using the data constant objects, such as Text, Int32, and Real64. Use this technique when you want to manually set each value in a one-dimensional array.

To create a one-dimensional text array with nine elements

1. Add a Text constant object to the work area (Data [image] Constant [image] Text).

2. Select Properties from the object menu. The Text Constant Properties dialog box appears. By default the Text constant object is configured as a Scalar.

3. To set the array size, click on 1D Array under Configuration, then click on the Size field and change it to 9.

4. To have a fixed number of elements, click on the Size Fixed checkbox as well. If you want to add additional elements on at the end, leave Size Fixed unselected.

5. Click on OK. The Text constant object appears as an array with elements 0000: through 0008:. VEE arrays are zero-based.

6. To set each value, click to the right of 0000: and type in the first element of your array. Use Tab (or down-arrow) to advance, Shift+Tab (or up-arrow) to back up among the array elements. Type in text strings for each of the elements.

Example of a nine-element, one-dimensional text array

See also

Constant

To Allocate an Array

To Build an Array in an Expression


To Allocate an Array

You can allocate arrays when you want to create them and set their values programmatically. You can create arrays of one or more dimensions.

Use the appropriate object, found under Data [image] Allocate Array, for the data type you are using. These objects include Alloc Text for text arrays and Alloc Boolean, Alloc UInt8, Alloc UInt16, Alloc Int16, Alloc Int32, Alloc Int64, Alloc Real32, Alloc Real64, Alloc Coord, Alloc Complex, and Alloc PComplex for numeric arrays.

Tips

All VEE array indexes are zero based. That is, the first element has index 0 in any dimension.

Allocated arrays can be 1 to 10 dimensions, and are usually "filled" with a repeated initial value.

An array of values is passed from object to object as a single data container.

Only one-dimensional integer and real arrays can be initialized with a linear or logarithmic ramp of values.

The memory required to allocate an array is determined by the number of dimensions, the sizes of the dimensions, and the data type.

The following procedures show how to allocate various types of arrays:

To Allocate a One-Dimensional Real Array

1. Add an Alloc Real64 object to the work area (Data [image] Allocate Array [image] Real64).

2. By default the Alloc Real64 object allocates a one-dimensional array with a linear ramp of values. Click on the Lin Ramp field (or its arrow) to show the drop-down menu.

3. You can select Init Value, Lin Ramp, or Log Ramp. Click on Log Ramp to select a logarithmic ramp of values.

4. Connect an XY Trace display object to the Alloc Real64 object and run the program.

To Allocate a Two-Dimensional or Larger Real Array

1. Add an Alloc Real64 object to the work area (Data [image] Allocate Array [image] Real64).

2. By default the Alloc Real64 object allocates a one-dimensional array with a linear ramp of values. Click on the Num Dims field (or its arrow) to show the drop-down menu.

3. Click on a dimension size from 2 through 10. The object adjusts to the new setting.

4. Change the size for the first dimension to 4, for the second to 3, and so on for each dimension. Then connect an AlphaNumeric display object to the output of the Alloc Real64 object.

5. Run the program. If Num Dims is set to 2, then resize the AlphaNumeric object to show the entire array. If Num Dims is greater than 2, the AlphaNumeric object displays the array size, since VEE display objects cannot display more than two dimensions.

To display more than two dimensions, you can use the To File object’s CONTAINER encoding to export data directly into PV-WAVE for visual data analysis.

More computer memory is used as you allocate larger arrays. Beyond five dimensions, you may need to declare smaller size parameters if your computer has the recommended amount of memory. If an array is too large, the VEE process may run out of memory, resulting in an error.

See also

To Build an Array in an Expression

To Change Values in an Array

To Create an Array Constant

To Collect Data into an Array

Allocate Array

To File


To Change Values in an Array

You can change values programmatically in an allocated array using an assignment operator such as a[2]=b. By modifying the assignment object’s formula and available terminals, you can assign new values to specific array locations, and use the output in other parts of your program.

To Set a New Value in a One-Dimensional Real Array

1. After adding an array allocation object (Data [image] Allocate Array [image]), add the assignment operator a[2]=b to the work area using the Function & Object Browser

On the toolbar, click on [image] then look under
Operators => Assignment => a[2]=b

2. Change the assignment operator’s formula to a[b]=c, and add a data input terminal.

3. Connect values to the following assignment operator pins:

a. Connect the Array data output pin of the Allocate Array object to the a data input pin of the assignment operator.

b. Connect a value to the b data input pin to identify the array location. An object such as an Int32 data constant can supply this input value.

c. Connect a value to the c data input pin. This is the new value you want to assign to the array location.

The following example program shows the connections. The assignment operator accepts array data on input pin a, then assigns the real value on input pin c to the location identified on input pin b. Output pin Result contains the new value, and output pin a contains the modified array.

See also

manual06.vee and manual07.vee in manual examples directory
Help [image] Open Example...

To Allocate an Array

Set Values

See Examples

Manual06.vee and Manual07.vee


To Extract Values from an Array

You can use the Get Values object to extract values from an array:

1. Add a Get Values object to the work area (Data [image] Access Array [image] Get Values). Double-click on the icon to show the open view object.

2. Connect any data source that outputs an array to the Ary data input terminal on Get Values. When Get Values operates, the SubAry terminal outputs a sub-array that depends on the expression in the Get Values expression field. The default expression Ary causes the entire original array to be output.

The rest of the data output terminals give information about the original array on the Ary terminal:

a. Type outputs the data type of the array.

b. NumDims outputs the number of dimensions in the array.

c. DimSizes outputs a one-dimensional array listing the size (the number of elements) of each dimension.

d. TotSize outputs the total size of the array (the total number of elements).

See also

manual08.vee

To Build an Array in an Expression

To Use Arrays or Array Elements in Expressions

Get Values


To Collect Data into an Array

Use the Collector to collect data into an array of unknown size. The following procedure builds an example program demonstrating the Collector. Use the Sliding Collector for 1D array data collection.

1. Add a Collector object to the work area (Data [image] Collector). Double-click on the icon to show the object’s open view.

2. Add the For Count, random, and AlphaNumeric objects to the work area and connect the pins as shown in the following program:

3. Run the program. (Resize the AlphaNumeric display to show the entire array.)

The Sliding Collector (Data [image] Sliding Collector) differs from the Collector in two significant ways:

1. The output is always a one-dimensional array.

2. There is no XEQ terminal. Instead, the Sliding Collector is set to trigger after a specified number of values.

See also

To Build an Array in an Expression

Collector

Sliding Collector

See Example

Manual09.vee


To Build an Array in an Expression

You can also build an array by specifying portions of other arrays in an expression. However, within an expression, all sub-arrays specified must have the same number of dimensions and contain the same number of values in each dimension.

Assume B is a 5-by-5 matrix (a two-dimensional array):

 | 0: | 1: | 2: | 3: | 4:
0: | 0 | 0.2 | 0.4 | 0.6 | 0.8
1: | 1 | 1.2 | 1.4 | 1.6 | 1.8
2: | 2 | 2.2 | 2.4 | 2.6 | 2.8
3: | 3 | 3.2 | 3.4 | 3.6 | 3.8
4: | 4 | 4.2 | 4.4 | 4.6 | 4.8

The expression [B[1,1],B[2,2],B[0,0],B[2,3]] returns the following one-dimensional array:

0: 1.2

1: 2.4

2: 0

3: 2.6

You can also build an array constant in an expression. For example, the expression [1.1,1.3,1.2] creates a three-element, one-dimensional real array:

0: 1.1

1: 1.3

2: 1.2

See also

To Extract Values from an Array

To Use Arrays or Array Elements in Expressions


To Use Arrays or Array Elements in Expressions

The topic To Extract Values from an Array explains that you can use an expression in a Get Values object to specify a sub-array. This topic explains how you can also specify an array or sub-array in an expression in any VEE object that has an expression field such as a Formula object.

In an expression, any reference to an array uses the following syntax:

Brackets [ ] are used after the array name to enclose the parameters specifying a sub-array. For example, if B is a two-dimensional array, B[0,0] specifies the first element in it.

The comma (,) separates array dimensions. Each sub-array operation must have exactly one specification for each array dimension.

The colon (:) separates a range of elements within one of the array dimensions.

The asterisk (*) is a wild-card character to specify all elements from a particular array dimension.

Note that all VEE array indexes are zero based. That is, the first element has index 0 in any dimension.

Examples

Assume A is a one-dimensional array, 10 elements long:

0: 100m

1: 0.2

2: 0.3

3: 0.4

4: 0.5

5: 0.6

6: 0.7

7: 0.8

8: 0.9

9: 1

The following expressions extract portions of array A:

A or A[*] returns the entire array A.

A[1] returns a scalar, which is the second element (index 1) in A:

0.2

A[1:1] returns a one-dimensional array with only one element, which is the second element (index 1) in A:

0: 0.2

A[0:5] returns a one-dimensional array that contains the first six elements (indexes 0 through 5) of A:

0: 100m

1: 0.2

2: 0.3

3: 0.4

4: 0.5

5: 0.6

A[2:*] returns a one-dimensional array that contains the third element through the end of the array; in this case, indexes 2 through 9 of A. (The indexes are redefined as 0 through 7 in the subarray.)

0: 0.3

1: 0.4

2: 0.5

3: 0.6

4: 0.7

5: 0.8

6: 0.9

7: 1

Assume B is a 5-by-5 matrix (a two-dimensional array):

 | 0: | 1: | 2: | 3: | 4:
0: | 0 | 0.2 | 0.4 | 0.6 | 0.8
1: | 1 | 1.2 | 1.4 | 1.6 | 1.8
2: | 2 | 2.2 | 2.4 | 2.6 | 2.8
3: | 3 | 3.2 | 3.4 | 3.6 | 3.8
4: | 4 | 4.2 | 4.4 | 4.6 | 4.8

The following expressions extract portions of array B:

B or B[*,*] returns the entire array B.

B[*] returns an error because it specifies only one dimension, and B is a two-dimensional array.

B[1,2] returns a scalar value from the second row (index 1), third element (index 2):

1.4

B[1,*] returns all of the second row (index 1) as a one-dimensional array:

0: 1

1: 1.2

2: 1.4

3: 1.6

4: 1.8

B[1,1:*] returns all of the second row (index 1), except for the first element (index 0), as a one-dimensional array:

0: 1.2

1: 1.4

2: 1.6

3: 1.8

See also

To Extract Values from an Array

To Build an Array in an Expression


Using Arrays to Store Test Results

TUsing Arrays to Store Test Results

Data types can be stored in two ways:

• Scalar values (that is, a single number such as 9 or (32, @10))

-OR-

• Arrays from 1 to 10 dimensions.

note

The overview of VEE data types is described in Data Type.

Indexing for arrays is zero-based in VEE, and brackets are used to indicate the position of the array element. For example, if the array A holds the elements [4, 5, 6], then

A[0] = 4, A[1] = 5, and A[2] = 6

The syntax for arrays is as follows:

Syntax Element | Description
colon | Used to indicate a range of elements. For instance, A[0:1] = [4, 5] in the array above.
asterisk (*) | a wildcard to specify all elements from a particular array dimension. A[*] returns all elements of array A.
commas | In the subarray syntax, commas are used to separate array dimensions. If B is a two-dimensional array with three elements in each dimension, B[1,0] returns the first element in the second row of B.

The syntax to access elements of an array can be used in the Formula object or any expression field, such as those in the To/From File object.

See Also

Lab 5-1: Creating an Array for Test Results

Lab 5-2: Extracting Values from an Array


The For/Each Object

The For/Each object is used to iterate an array. It cannot be used for records. In the following example, a one dimensional array is iterated using the methods available prior to the For/Each object was added.

This same process with the For/Each object takes only three objects as opposed to the five objects required in above.

As you add dimensions to the array, the old method becomes increasingly complex to the point it is almost unmanageable. In comparison, the For/Each object supports ten dimensions making it very easy to expand to the full extent of VEE’s array structures.


Array Functions Operations

Most elementary math functions in VEE, such as log(), sin()and cos() can accept an array as a parameter and return an array. Some specialized functions are handy for performing array math and manipulations. Other functions are not useful with arrays. Functions that are useful in array operations include:

• ramp() can be used to generate “loop” counts.

• concat() concatenates two arrays and returns a one-dimensional array.

• totSize() gives total number of elements in an array.

• signof() detects a value’s sign ( -1 if < 0, 0 if = 0, 1 if > 0).

• abs(x) sets the absolute value.

• rotate() rotates elements in array.

• sum() sums all elements in an array.

• sort() sorts an array.

• randomize() generates array of random numbers.

• min() finds the minimum value of a data set.

• max() finds the maximum value of a data set.

• clipUpper() clips below the maximum given value.

• clipLower() clips above the minimum given value.

A useful feature in Formula objects is the ability to define expressions as arrays. Notice that you must insert commas between array elements. The following expression generates an array containing the double, reciprocal, square, and natural log of the input named B:

[2*B, 1/B, B*B, log(B)]

The following examples show how to manipulate arrays using expressions in a Formula object. Just connect an object containing the array to the Formula object's input pin.

Example

You can take an existing array and perform math calculations on selected elements using an assignment expression. The following example changes the values in one row of a two-dimensional array. The expression in the Formula object performs this task on the input array A=[1,2,3,4], where row 0 contains 1 and 2 and row 1 contains 3 and 4.

The expression multiplies the elements in the second row by 4, then assigns the results to array A. Notice that the Result terminal outputs only the changed values and the A terminal outputs the entire array with the new values.

See Also

Splitting a Large Array, Combining Arrays, Multiplying a Vector by a Matrix, Inserting Elements into an Array, Converting a Vector to a Matrix


Array Operations Techniques

VEE is optimized for array math. While you can perform array operations using traditional loop constructs, they tend to degrade program speed. This section shows ways to use the Formula and other objects to perform math operations on arrays.

note

You can adapt the examples in this section and use assignment operators to avoid using time-consuming computational loops. Since these techniques are not always obvious, be careful about using them and be sure to document your programs thoroughly.

This section shows some array operations techniques for VEE, including comparison of array operation techniques, accessing arrays in expressions, performing array math operations, and using variables in expressions.

Comparison of Array Operation Techniques

The program segments in the following two figures compare techniques for generating an array containing all the values of sine and cosine for each degree from 0 to 360. If you try each of these techniques, you will find that the first technique takes more time.

Converting the logic contained in this series of objects to a mathematical operation, results in the expression shown in the Formula object in the following figure . This technique does the same calculations in less time:

Though this technique is much faster, it is not obvious that it does the same calculations. Here is an explanation of the expression’s operation:

1 The ramp() function generates an array of 360 values, increasing from 0 through 359.

2 The two ramp functions generate identical arrays, each operated on by the sin() and cos() trigonometry functions. Most VEE functions that normally accept and return a scalar value can accept and return an array as a parameter.

3 Though the Formula object actually contains two formulas, their outputs are converted to an array format because they are contained in the square brackets.

This technique may not be the best choice for all programs. The sine and cosine operations are done on the entire arrays produced by the ramp() functions, not on each value as it is generated. If your program must operate on each value as it is generated, use a loop structure instead of an expression that operates on the entire array.

Accessing Arrays in Expressions

Arrays in expressions can be used just like scalars. Refer to them by their name. Array constants can be entered directly into an expression (such as [1,2,3]). VEE requires that you insert commas between array elements.

note

Array indices are 0-based. The indices start with zero and continue to n-1, where n is the number of elements in that particular dimension.

You can use expressions to access portions of an array. Once you have specified the sub-array in the expression, you can output the sub-array or use it in further expression calculations.

You can access only contiguous sub-arrays from each array. To access sub-arrays, you must specify a parameter for each dimension in the array. Use the following characters to specify array parameters:

• A comma “,” separates array dimensions. Each sub-array operation must have exactly one specification for each array dimension.

• A colon “:” specifies a range of elements from one of the array dimensions.

• An asterisk “*” is a wildcard to specify all elements from that particular array dimension.

note

Waveform time spans, spectrum frequency spans, and array mappings are adjusted according to the number of points in the sub-array. For example, if you have a 256 point waveform (WF) and ask for WF[0:127], you will get the first half of the waveform and a time span that is half the old span.

Examples: Values Returned from Array

The following expressions show values returned where A is a one-dimensional array (Array 1D) ten elements long.

• A[1] accesses the second element in A and outputs a scalar.

• A[0:5] returns a one-dimensional sub-array that contains the first six elements of A.

• A[1:1] returns a one-dimensional sub-array that contains one element, which is the second element of A. Note the difference between this and the first example, A[1].

• A[2:*] returns a one-dimensional sub-array that contains the third through the tenth elements of A.

• A or A[*] returns the entire array A.

• A[1,2] returns an error because it specifies parameters for a two-dimensional array.

• B is a 5x5 matrix (an Array 2D).

• B[*] returns an error because it specifies only one parameter and B is a two-dimensional array.

• B[1,2] returns a scalar value from the second row, third element.

• B[1,*] returns all of row one as an Array 1D.

• B[1,1:*] returns all of row one, except for the first element, as an Array 1D.

• B[4,1:4] returns an Array 1D that contains four elements: the second through fifth values from row 4.

• B[5,5] returns an error because arrays are zero-based. The array can only be accessed through B[4,4].

• B[1 1] returns an error because a comma must separate the dimension specifiers.

Building Arrays in Expressions

You can build an array from elements of other arrays or sub-arrays. Each element in the expression must specify the same number of dimensions and contain the same number of values in each dimension.

For example, the following expressions show values returned where A is a one-dimensional array (Array 1D) ten elements long and B is a 5x5 matrix.

• [1,2,3] returns a three-element Real Array 1D that contains the values 1, 2, and 3.

• [A[0], A[5:7], A[9]] causes an error because both scalar and Array 1D elements are specified.

• [A[0:4], B[0,*]] returns a ten element Array 2D (of size 2 by 5) that contains the first five elements from A as the first row and the first row from B as the second row.

• [A[0], A[1], B[2,3], A[5]] returns a four element Array 1D that contains the first and second element of A, the element from the third row and fourth column of B and the sixth element of A.

Performing Array Math Operations

Math operations on arrays use another set of simple rules. Elementary scalar arithmetic operations on arrays simply perform their operations on each element in the array:

• A*2 multiplies each element in the array by 2.

• A-4 subtracts 4 from each element in the array.

• Arrays used in functions, like sin([1,2,3]), have the sin function applied to every element of the array.

Math operations between two arrays that have the same size and dimensions perform the operation between corresponding elements of the arrays:

• A*B multiplies each element of the array A by the corresponding element of array B. This does not perform a “matrix multiply”, which is a relatively complicated multiplication of rows times columns and summation that results in a scalar. VEE has a built-in matrix function to do that, called matMultiply(A,B).


Combining Arrays

To Combine Arrays

The following example shows how to concatenate multidimensional arrays. The concat(x,y) function is useful for this task when used in a Formula object, even though it can generate only a one-dimensional output. However, it will work only if the number of rows or columns is fixed (a constraint that is usually met in practice). The Formula object here contains an expression that concatenates a pair of arrays that have two rows:

The concat() function concatenates two arrays and produces a one-dimensional array. The expression strips out the rows of each of the arrays, concatenates them and then joins them back together into a two-dimensional array with two rows containing the combined number of elements in each row.

See Also

Array Functions Operations, Splitting a Large Array, Multiplying a Vector by a Matrix, Inserting Elements into an Array, Converting a Vector to a Matrix


Splitting a Large Array

To Split a Large Array

You can display the elements of a single 2048-element array as 16 sets of 128 elements each. While the problem focuses on the display of the data, rather than its generation, it may help to approach a solution that involves breaking up the array.

The program below shows how to break up the array in order to achieve the display goal.

The ramp() function simply generates a 2048-element array with values from 0 to 2047 for test purposes. The For Count object ticks off each of the 16 individual arrays to be generated, while the Formula box selects the appropriate sub-array using indexes generated from the count:

A[0:127], A[128:255], A[256:384], ..., A[1920:2047]

Of course, this assumes a fixed array size, number of subarrays and size of subarrays. An error occurs if any of these are mismatched.

See Also

Array Functions Operations, Combining Arrays, Multiplying a Vector by a Matrix, Inserting Elements into an Array, Converting a Vector to a Matrix


Multiplying a Vector by a Matrix

To Multiply a Vector by a Matrix

The following example shows how to multiply a vector

[ X1, X2, X3, X4 ]

times a matrix

[[ y11, y12, y13, y14 ],

[ y21, y22, y23, y24 ],

...

[ y51, y52, y53, y54 ]]

to get the result

[[ X1*y11, X2*y12, X3*y13, X4*y14 ],

[ X1*y21, X2*y22, X3*y23, X4*y24 ],

...

[ X1*y51, X2*y52, X3*y53, X4*y54 ]]

VEE can multiply a scalar times a vector and can perform matrix multiplication. A scalar multiplication multiplies every element in a matrix by a scalar to give a result matrix of the same size as the original. A matrix multiplication is an operation between an MxN matrix and an NxM matrix that yields a scalar. The required operation for this example does not match either case.

The operation here is effectively a scalar multiplication of each row of the matrix by each element of the vector. The implementation uses array manipulation techniques. Consider a data set consisting of a vector V of the form

[ 1, 2, 3, 4 ]

and a matrix M of the form

[ [1, 2, 3, 4, 5, 6, 7, 8 ],
[10, 20, 30, 40, 50, 60, 70, 80 ],
[100, 200, 300, 400, 500, 600, 700, 800 ],
[1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000 ] ]

The desired result is

[ [1, 2, 3, 4, 5, 6, 7, 8 ],
[20, 40, 60, 80, 100, 120, 140, 160 ],
[300, 600, 900, 12K, 15K, 18K, 21K, 24K ],
[4000, 8000, 12K, 16K, 20K, 24K, 28K, 32K ] ]

The expression in the Formula object below does the multiplication. The matrix array is connected to terminal M and the vector array is connected to terminal V. Tests indicate that this is only about 50% slower than a scalar multiplication of the same array.

See Also

Array Functions Operations, Splitting a Large Array, Combining Arrays, Inserting Elements into an Array, Converting a Vector to a Matrix


Inserting Elements into an Array

To Insert Elements into an Array

The following example shows an expression that inserts one or more data elements into an existing array. The inputs are

A is the Index Value
B is the New Data
C is the Original Array

The revised array is output on Result.

The Index Value on A indicates what the starting index of the new data should be. If A is 0 or less, the New Data on B is concatenated to the beginning of the Original Array on C.

If A is greater than or equal to the length of the Original Array, the New Data is concatenated to the end of the Original Array. If A is some value in between, the Original Array is broken into segments around the Index Value and the New Data is spliced into it.

The next example is similar to the previous one. It builds a data queue with array operations. A queue is essentially an array of fixed length, where new elements are added at one end and numbers shift down to the other end, where numbers fall off and are lost.

The ramp() expression allocates an initial empty array of ten elements to act as a queue. The On Cycle loop (cycle is set to 1 second) begins and sends random numbers to the head of the queue every second. The Formula: Queue takes the last nine elements of the OldData input and concatenates it with a new random number on the NewData input. The array output on Result is fed back as the next set of OldData and sent to the next program segment. A new random number is sent to NewData on the next cycle.

See Also

Array Functions Operations, Splitting a Large Array, Combining Arrays, Multiplying a Vector by a Matrix, Converting a Vector to a Matrix


Converting a Vector to a Matrix

To Convert a Vector to a Matrix

There are occasions when you can get the results you need by using transaction objects in place of array functions. The example below uses a From String object to convert a vector (one-dimensional array) into a matrix (two-dimensional array). Run the vector through the From String and specify the array format you like as an output as shown in the next program. The conversion between Real and Text data types is automatic in VEE.

For example, let us convert a one-dimensional 9-element array into a 3x3 two-dimensional array:

The vector output from the ramp() function is

0,1,2,3,4,5,6,7,8

The From String transaction converts it to the row-ordered matrix

0,1,2
3,4,5
6,7,8

If you prefer a column-ordered matrix, use the transpose() (transpose matrix) function to get the following result

0,3,6
1,4,7
2,5,8

Another way to convert a vector to a matrix is with the Formula build array syntax. You know that the syntax [1,2,3] generates a one-dimensional array with three elements. Similarly, if a is a one-dimensional array 10-long, the syntax [a] generates a 1x10 two-dimensional array. Again transpose() can be used if you want a 10x1 matrix.

See Also

Array Functions Operations, Splitting a Large Array, Combining Arrays, Multiplying a Vector by a Matrix, Inserting Elements into an Array


Combining Disparate Elements into One Array

To Combine Disparate Elements into One Array

The program shows the method required to take several data sets from a device and get a resulting data set that consists of the maximum values from all the individual data sets:

This program simulates input data by using a Noise Generator. It gets an initial data set and puts it in the global variable sumdata, then enters a loop to obtain new data or quit the program.

Pressing the Get Data button gets a new waveform from a Noise Generator, then recovers the data in sumdata with a Get Variable object; these two waveforms are summed into a Formula object, which processes them and puts the result back into sumdata using a Set Variable object.

The Formula object accepts the new array data on pin A and the array sumdata on pin B. The expression cliplower(a,b) outputs a result array with the value of A if A > B and the value of B otherwise. If you use clipUpper instead, you would obtain minimum values.

See Also

Comparing Two Arrays, Using Alternate Expressions, Choosing Efficient Techniques


Comparing Two Arrays

To Compare Two Arrays

The example here compares two arrays of random numbers and determines how many numbers in the first array are greater than those in the second array. Comparisons between values typically use relational operators (such as ==, != and <=) and the triadic operator (A < B ? C : D), but these will not solve this problem. Though they accept any data shape, they only return scalar results. You can still perform relational operations by other means that yield an array result.

The randomSeed() function seeds the random-number generator with a seed that varies rapidly with time. This ensures that the data varies between different runs of the program. The two randomize() functions each generate an array of 1000 random numbers in the range 0 to 1. Finally, the expressions in the Formula objects perform the summation

sum(clipLower(0,signof(A-B)))

Here is how each part of the expression works:

1 A-B provides an array where values are positive if A > B, zero if A == B, and negative if A < B.

2 signof(A-B) converts positive numbers into 1, negative numbers into -1, and leaves 0 at 0.

3 clipLower(0,signof(A-B)) strips all the -1 values out of the array, resulting in an array that is 1 if A > B and 0 otherwise.

4 sum() then adds up the 1s and outputs the number of comparisons where A > B.

See Also

Combining Disparate Elements into One Array, Using Alternate Expressions, Choosing Efficient Techniques


Using Alternate Expressions

To Use Alternate Expressions

Conventional relational operators can be implemented for array operations using other techniques:

• A == B: (1-abs(signof(A-B)))

• A != B: abs(signof(A-B))

• A > B: clipLower(0,signof(A-B))

• A < B: clipLower(0,-signof(A-B))

• A >= B: (1-clipLower(0,-signof(A-B)))

• A <= B: (1-clipLower(0,signof(A-B)))

Notice how subtracting an array of 1s and 0s from 1 performs a NOT operation on the array. Similar techniques can be used for comparison with scalar values, rather than other arrays. You can also perform Boolean operations on the resulting arrays of 1s and 0s.

For example, suppose that A1 and A2 are two such arrays. The following logic operations hold:

• NOT A1: 1 - A1

• A1 AND A2: A1 * A2

• A1 OR A2: signof(A1 + A2)

• A1 XOR A2: 1 - abs(signof((A1 + A2) - 1))

You can use the results of these computations to perform “masking” on arrays of the original values through multiplication. Those values that match to 0 are removed and those that match to 1 are retained.

See Also

Combining Disparate Elements into One Array, Comparing Two Arrays, Choosing Efficient Techniques


Choosing Efficient Techniques

To Choose Efficient Techniques

Applying the previous techniques could result in programs with Formula objects containing huge logic operations that are difficult to maintain. While the goal is to eliminate or reduce loops by replacing multiple objects with Formula objects, you could also use UserFunctions. A good understanding of array-manipulation techniques allows you to bypass complicated formal logic operations for more direct solutions.

The following example shows the choices you can make in array manipulation. Suppose an array of 8-bit unsigned data received from an I/O device is converted by VEE into 32-bit signed integer data and you want to get the real values back. You can do this in a single expression by adding 256 to each value of the return array:

(A + (clipLower(-1,clipUpper(0,A))) * (-256))

This expression performs the following operations:

1 clipUpper(0,A) converts all positive values to 0.

2 clipLower(-1,clipUpper(0,A)) converts all negative values to -1 (recall that the inputs are integers, not reals). This creates an array that has -1 for each negative value and 0 otherwise.

3 clipLower(-1,clipUpper(0,A)) * (-256) multiplies that array by -256 creating an array that has 256 for each negative value and 0 otherwise. This array is then added to the original array to offset all the negative values to their “true” positive value.

Another solution could have used relational operations as shown previously, but it would have been much more complicated than this direct solution.

A very useful object for array computations is the Comparator, which allows extraction of array elements that meet specific criteria. Suppose you want to determine the transitions in the following data stream:

0 0 0 0 1 1 0 0 1 1 0

The solution shown below is the easiest way to find the indexes of the array elements where the value makes a transition from 0 to 1 and the reverse.

Although the program contains a Comparator, the key is the Formula object containing the expression

A[1:(totSize(A)-1)] - A[0:(totSize(A)-2)]

To see how this works, add array indexes to the data stream:

B0:0 1:0 2:0 3:0 4:1 5:1 6:0 7:0 8:1 9:1 10:0

The array indexes are marked where a transition occurs. The expression above performs a subtraction of the input array from itself, staggered by one index, to yield the following new array:

0:0 1:0 2:0 3:0 4:1 5:1 6:0 7:0 8:1 9:1 10:0

- 0:0 1:0 2:0 3:0 4:1 5:1 6:0 7:0 8:1 9:1 10:0

0:0 1:0 2:0 3:1 4:0 5:-1 6:0 7:1 8:0 9:-1

The Comparator checks the Result array to see which elements are equal to 0. Array elements that fail the test are the indexes and are returned on the Failures terminal as an array of X-Y coordinates giving the index and value of the failure. To retrieve only the index values, the Unbuild Coord object separates the X and Y values. Then the X index values are incremented by 1 to eliminate the effects of the staggered subtraction.

The data obtained in the subtraction not only indicates the index of the transaction, but its direction: 1 for a positive transition, -1 for a negative. This operation is basically a difference-equation approach to performing a differentiation.

See Also

Combining Disparate Elements into One Array, Comparing Two Arrays, Using Alternate Expressions


To Create a Record Constant

The best way to see how to create a record constant is to try an example as shown below.

To create a single record

1. Add a Record constant object to the work area (Data [image] Constant [image] Record).

2. Note that the Record constant is unlike any of the other constant objects. It has two named fields (A and B by default), each of which has a type-in field. Click on the button labeled A. The Record Field Attributes dialog box appears.

3. You can change the name of the field by typing in a new name in place of A. Change the field name to Name, but leave the data type set to Text and the number of dimensions set to 0 (scalar). Click on OK.

4. Now click on the button labeled B. Change the field name to Empl_No, and then click on Real64 (or the arrow) to show the drop-down menu.

5. Click on Int32 to select the integer data type, but leave the number of dimensions set to 0. Click on OK.

6. Enter John Doe in the type-in field next to Name, and enter 111222 in the type-in field next to Empl_No, as shown below. Connect an AlphaNumeric display object to the output pin, and run the program:

To create an array of records

1. Continuing with the previous procedure, select Properties from the object menu of the Record constant.

2. Now click on the radio button in front of 1D Array to convert the Record constant into an array of records. Set the Size to 3, and then click on OK. The object changes format.

3. The First, Prev, Next, and Last buttons let you scroll through the array of records. To change each record in the array:

a. Click on Next to scroll to the second record. Change the name to Sue Smith and the number to 111223.

b. Click on Next to scroll to the third (and last) record. Change the name to Richard Roe and the number to 111224.

4. Now run the program. Re-size the AlphaNumeric display to show the entire array of records:

See also

To Collect Data into a Record

Record Constant


Using Records

To Use Records to Store Mixed Data Types

The Record data type can store different data types in a single data container. Record can include any VEE data type. The data can be in the shape of a Scalar or an Array. You can store a test name, a time stamp, and a real array in a single data structure.

  • The individual elements in a Record are stored as fields and are accessed using a dot notation. For example, Rec.Name accesses the field called Name within a Record called Rec. In an array of records, Rec[2].Name signifies the Name field in the third record in the array. All arrays start indexing at zero.

There are several benefits to structuring test data using the Record data type:

• You can create logical groupings of mixed data types in a single container, which makes a program easier to develop and maintain. For example, you might use the following fields for a record storing test data: test name, value returned, pass or fail indicator, time stamp, nominal value expected, upper pass limit, lower pass limit, and a description of the test.

• You can manipulate a single data container rather than eight separate data containers. This makes the program simpler and more readable.

• You can store and retrieve Records from DataSets in VEE. A DataSet is a special file created to store records. When you retrieve records from a DataSet, you do not have to know the data types. VEE provides objects to retrieve, sort, and search the information stored in DataSets.

See Also

Lab 5-4: Using Records

To Create a Record Constant

To Collect Data into a Record

To Extract a Field from a Record

To Change a Field in a Record

To Programmatically Build Records

To Access Records

To Understand Record Containers


To Collect Data into a Record

Use the Build Record (Data [image] Build Data [image] Record) object to build large arrays of records. This topic uses an example program to show how to use the object.

Example

1. Open the program manual10.vee and run the program.

The Build Record object builds a record from the data on its data input terminals and outputs a record on its Record output terminal. The program works as follows:

The Text array on input A is a list of names.

The Int32 array on input B is a list of employee numbers.

The Build Record object is set for an output shape of Scalar, so it outputs the scalar record {<Text Array 1D>, <Int32 Array 1D>} consisting of two record fields, each containing a one-dimensional array. The first record field is the array of names, and the second is the array of employee numbers. The input arrays need not be the same size.

2. Though Scalar is the default, you can change the output shape:

a. Click on Scalar to display Array 1D.

b. Run the program. An array of records appears in the display.

The Build Record object matches each name and employee number to form an individual record in the array of records to be output on the Record terminal. When the output shape is set to Array 1D, the input arrays must be of the same size.

See also

Build Record


To Extract a Field from a Record

To Extract Fields from a Record

Use the rec.field object (Data [image] Access Record [image] Get Field) to extract a field from a record, and use the UnBuild Record object (Data [image] UnBuild Data [image] Record) to extract all fields. This topic uses example programs to show how to use the objects.

Get Field Example

Open the program manual11.vee from your manual examples directory (Help [image] Open Example...), and run the program.

The Build Record object builds a record consisting of field A (a waveform), and field B (a scalar).

The upper rec.field object uses the expression rec.A to extract "field A of record rec" (the waveform), which is displayed by the Waveform object.

The lower rec.field object uses the expression rec.B to extract "field B of record rec" (the time), which is displayed by the AlphaNumeric object using the time stamp format.

UnBuild Record Example

Open the program manual12.vee from your manual examples directory (Help [image] Open Example...), and run the program.

The Build Record object builds a record consisting of field A (a waveform), and field B (a scalar).

The UnBuild Record object extracts fields A and B, then outputs the data on their respective pins.

See also

To Use a Record in an Expression

Get Field

SubRecord

UnBuild Record


To Change a Field in a Record

Use the assignment operator object from Data [image] Access Record [image] Set Field to change a field in a record or in an array of records. This topic uses example programs to show how to use the object.

Change Field in Record Example

Open the program manual13.vee and run the program.

In the assignment operator titled Set Name Field, the expression means: Let field Name of record Rec be equal to the value on data input terminal A. The record is connected to the rec data input terminal.

In the assignment operator titled Set Empl_no Field, the expression means: Let field Empl_no of record Rec be equal to the value on data input terminal A.

The record continues through to the display as field changes are made.

Change Field in Array of Records Example

In the following program, the expression Rec[5].Name = A specifies that array element 5 in the Name field of record Rec is to be set equal to the data on input terminal A.

See also

Set Field


To Use a Record in an Expression

You can use the record syntax Rec.Field, where Field is the name of a field within record Rec, in any VEE expression field. In the following program the expression (A.High + A.Med)/A.Low adds fields High and Med of record A, and divides the result by field Low.

Tips

To avoid confusion, give your record fields descriptive names.

You can combine the record syntax with array syntax to access an array element from a record field.

See also

manual14.vee in manual examples directory Help [image] Open Example...

Processing Data


Understanding Record Containers

To Understand Record Containers

There are several VEE objects that allow you to create and manipulate records, including Record, Build Record, UnBuild Record, Merge Record, SubRecord, Set Field, and Get Field. All these objects are located in the Data menu.

A container of the Record data type has named fields which represent data. You can have as many named fields as you like in a record. Each field can contain another record, a scalar, or an array.

The Record object allows you to create records by manually entering a value for each field. Just configure the Record object as a scalar (array elements = 0) or as an array (array elements = non-zero) with the Properties dialog box, accessed from the object menu.

The following Record object is configured as a record array with four array elements. The record consists of five fields: the Text fields (Name, Address and City) and the Int32 fields (EmplNo and Zip). The Record object allows you to step through the record from one array element to the next by using the First, Prev, Next, and Last buttons. You can edit each field as you go.

When the program is run, the entire record is output on the Record output pin. The AlphaNumeric display shows the entire record with four array elements (0 through 3) each consisting of five record fields enclosed in braces ("{}").

See Also

Build Record

Accessing Records

Programmatically Building Records


Accessing Records

To Access Records

The following two example programs show one way to access a record and extract individual fields.

Use the Get Field object to extract an individual field from the record. Get Field is located under Data [image] Access Record. For the example, in the first program, Get Field objects are used to extract the entire Name and EmplNo fields: The Get Field object is a Formula object with the default expression rec.field.

Use the "dot" syntax to access individual fields, for example: Rec[*].Name and Rec[*].EmplNo. This syntax is described in Processing Data.

Rec[*].Name means "get the Name field from all elements of the record array on the Rec input pin." This syntax can be used in an expression in a Formula object or in any other expression that is evaluated at run time. For example, you could use this syntax in a transaction in the To String object.

Use the syntax Rec[1].Name and Rec[1].EmplNo to obtain just the second element ("element 1") of each field as follows.

To retrieve several or all fields from a record use the UnBuild Record object as follows.

The UnBuild Record object allows you to add outputs for every field in the record and provides Name List and Type List outputs. These outputs list the name and type of each field in the record.

The program is saved in the file manual38.vee in your examples directory.

note

Data cannot be automatically converted to and from the Record data type. For example, to send Record data into a Real input terminal you must extract the field from the Record with the Unbuild Record object or use Get Field with the Rec.A syntax as described previously.

See Also

Build Record


Programmatically Building Records

To Build Records Programmatically

The Record object is useful for creating and editing simple records. However, it is cumbersome for creating large records. You may also want to create a record from existing data. In such cases, use Build Record to build a record.

When you build a record from individual data components with Build Record, you must define the data shape of the output Record container. The Build Record object gives you two Output Shape choices: Scalar and Array 1D. In most cases you will find that Scalar, the default, is the appropriate choice for Output Shape.

The example shows the difference between Scalar and Array 1D in the output record built from two input arrays:

In above program, when Scalar is selected the output record is a scalar record consisting of two fields, each being one of the input arrays. On the other hand, when Array 1D is selected for the same input data, the output record is a record array with the same number of elements as the two input arrays. The data is matched, element for element, in the output record.

If two input arrays have different numbers of elements, only Scalar is allowed as the Output Shape. To create an Array 1D output record, all input arrays must have the same number of elements or an error will occur. However, you can mix scalar and array input data, as shown in the following example.

In this case, the scalar Real value 1 is repeated five times in the output record array if Array 1D is selected.

See Also

Build Record


Using DataSets

To Use DataSets

DataSets can retrieve one or more records. VEE objects unpack the records. Therefore, by storing records to DataSets instead of files, you do not have to remember the data types. You can also perform sort and search operations on the data, creating your own customized test database.

VEE data (including waveforms) can be built into records and later retrieved. You can also store records into a file, called a DataSet. The To DataSet and From DataSet objects allow you to store and retrieve records to and from DataSets. They are located in the I/O menu.

A DataSet is a collection of Record containers saved into a file for later retrieval. The To DataSet object collects Record data on its input and writes that data to a named file (the DataSet). See the following example.

Two waveforms, a sine wave and a noise waveform, are output to the Build Record object which builds a record. The record is then output to the To DataSet object which writes the data to the file myData. Clear File at PreRun is checked so any data previously stored in myData is cleared.

Once the data has been saved as a DataSet, use From DataSet to retrieve the record, which can then be unbuilt if desired. The following program shows this technique.

The From DataSet object retrieves the record data from myData and outputs the data to Unbuild Record, which separates out the sine wave and noise data fields. In this example, the sine wave, the noise waveform, and the sum of the two waveforms are each displayed in a separate XY Trace object.

The pair of programs of this last example are saved in the files manual40.vee and manual41.vee in the examples directory.

Customizing a Simple Test Database

You can search and sort a DataSet for information, such as test name, time stamps, test parameters, test values, pass or fail indicators, and test descriptions. Therefore, DataSet records can act as a test database. To search for information, you can use the From Data Set object as follows:

• The expression field in the From Data Set object is used for search operations.

• The function sort() can be used to sort records using a specified field.

See Also

Lab 5-5: Using Datasets

Lab 5-6: Using Search and Sort Operations with DataSets


To Enable the Scroll Bar on Panel View

To Enable Scroll Bars in Panel Views

In the Property window, set ScrollBarsEnabled to True to enable the scroll bars for a panel view. By default, ScrollBarsEnabled is False. ScrollBarsEnabled is not available for detail view.

See Also

To Navigate programs, Minimap, To Navigate an Operator Interface Panel


To Create a Variable

You can create a variable that is declared or undeclared, and as local or global. An undeclared variable is created when you assign a value to it in an expression in an object such as Formula, or by using the Set Variable object. However, declaring a variable before assigning it a value has several advantages. These include scope, faster program execution speed, and preservation of a variable’s data type and shape.

To create an undeclared local variable

An undeclared local variable is created when data on an object’s data input terminal is used in an expression. This variable is local to the object. The variable name in the expression must match the input terminal’s name. The following figure shows an example of a Real64 Constant object connected to a Formula. The variables in the Formula expression (A, B, and C) get data through the corresponding input terminals, and are local to Formula. If you added output terminals to Formula (in addition to Result), they are also undeclared local variables to Formula.

To create an undeclared global variable

1. Click on Data [image] Variable [image] Set Variable and place a Set Variable object in the work area.

2. Click in the Name field and type a new variable name if desired. You can use any valid variable name in place of globalA for a variable.

3. Connect a data object to the Data terminal of the Set Variable object. The variable will be created and set to the data value. This undeclared global variable is now available for use in any expression in your program.

To create a declared local or global variable

1. Decide whether you want to declare a global or local variable. If you want to declare a local variable, open the context (UserObject or UserFunction) or library where you will use the variable.

A global variable can be declared and used anywhere in your program. A local variable must be declared and used in a specific context or library.

2. Click on Data [image] Variable [image] Declare Variable and place the Declare Variable object in the work area.

3. Click in the edit field beside Name, and enter a variable name. This should be a unique name to avoid conflict with other variables.

4. Click in the Scope edit field to set the variable’s scope.

Global makes the variable available anywhere in your program regardless of the context where the Declare Variable object exists.

Local to Context limits the variable’s use to the UserObject or UserFunction (and any UserObjects nested inside them) in which the Declare Variable object exists.

Local to Library limits the variable’s use to the library of UserFunctions (local or imported) where the Declare Variable object exists.

5. Click in the Type edit field to set the variable’s data type. Data assigned to this variable during program execution must match the declared data type or an error will result.

6. Click in the Num Dims edit field to set the variable as an array with the dimensions you select.

Tips

A declared variable must be initialized using Set Variable or an assignment operator before it can be used.

If a global variable and local variable use the same name, a conflict exists, and the local variable takes precedence.

Variable names are not case sensitive (globalA is equivalent to GlobalA).

You can use any type of data, such as records, to set an undeclared variable.

To view a list of variables in a program, click the WatchWindow button on the toolbar (or use View [image] WatchWindow) to open WatchWindow dialog box. Declared variables are listed when a program is opened. Undeclared globals are listed after a program is run. You can edit the value of variables in WatchWindow. The program can continue execution incorporating any changed values. The Program Explorer also lists variable names.

View Variables button

Program Explorer button

See also

To Delete a Variable

To Use a Variable

To Use a Global Array

Default Preferences (Delete Variables at PreRun)

Set Variable

WatchWindow


To Delete a Variable

1. Click on Data [image] Variable [image] Delete Variable and place a Delete Variable object in the work area.

2. Choose whether to delete a specific variable, or all variables.

To delete a specific global variable by name, click on By Name (default), then click in the text field and enter the variable’s name.

To delete all variables, click on All Variables.

Tips

Delete Variable resets the values in a declared variable’s data container to uninitialized values; it does not delete the variable’s name.

Delete Variable deletes an undeclared variable’s values and its name.

Variable names are not case sensitive (globalA is equivalent to GlobalA).

The Delete Variable object will error if the variable referenced by name does not exist.

The name field may be added as a control input to Delete Variable.

See also

To Create a Variable

Delete Variable


To Use a Variable

Use the Get Variable object (Data [image] Variable [image] Get Variable) to access a variable that has been initialized, or use the variable name in an expression. These methods are very useful in a UserObject or UserFunction. The Get Variable object must be used in the correct context if the variable has been declared local or global.

Tips

To avoid using obsolete data from a previous program run, the values of all variables are deleted (cleared) at PreRun, when you run the program. To turn off Delete Variables at PreRun, click on the Default Preferences button on the toolbar (File [image] Default Preferences).

Default Preferences button

If values are deleted at PreRun, you must connect the sequence output pin of the Set Variable object to the sequence input pin of any object that uses the variable. Otherwise, an error occurs because the variables have no defined values.

You can use a variable in any object that includes an expression. However, you cannot include an expression in the name field of a Get Variable object.

You can define a global variable in the main context of an VEE program and then access the variable from within the context of a UserObject or UserFunction. This requires a sequence input connection only to the UserObject or to the Call object.

The example program manual18.vee shows how variables are declared, initialized, and used in the Main and UserObject contexts. It can be found in the Manual examples directory (Help [image] Open Example).

See also

To Create a Variable

Get Variable

WatchWindow


To Use a Global Array

You can declare a variable to be a global array. This makes array handling easier because you can then access the array from anywhere in your VEE program. This topic uses an example program to show how to use the object.

Example

1. Open the program manual19.vee from your manual examples directory (Help [image] Open Example...), and run the program.

The two Formula objects use array syntax to access elements of the global array. For example, the expression globalA[3] retrieves the element numbered 0003 (the fourth element) in the global array globalA. You can use this method with records.

See also

To Create a Variable


Setting Initial Values

To Set Initial Values

You must have set initial values before accessing any variables or VEE generates an error. Here is a variable example.

The Set Variable must set the global variable before the Get Variable attempts to retrieve it. To ensure this, the sequence output pin of the Set Variable object is connected to the sequence input pin of the Get Variable object. If this is not done, the Get Variable may try to access a non-existent global variable and an error will occur.

note

If the property Delete Variables at PreRun is not set, you may not receive an error and may receive old data instead.

When declared variables are created, they are not initialized and must have a value set in them before they are accessed via the Get Variable object or used in expressions. If they do not, your program will generate an error. You set values via the Set Variable object or by using the Formula object.

If the variable is an array or a record, when using the Formula object you must set the values of the entire array or record before trying to access any of the elements. The next example shows two different ways to initialize values from a Formula object.

See Also

To Create a Variable

To Access Variable Values


Accessing Variable Values

To Access Variable Values

Once you have named a variable, you can access its value as many times as you want in your program. You can use several methods to retrieve the variable value. In the following example, the value stored in the global variable globalA is retrieved once with a Get Variable object, a second time by including the name globalA in an expression in a Formula object, and a third time by including the name globalA in a transaction in a To File object:

note

You can include the name of any global variable in any expression in a Formula object or in any other expression that is evaluated at run time.

See Also

To Use a Variable


Using Variables in Libraries

To Use Variables in Libraries

Because only UserFunctions are loaded when the library is imported, when you use Declare Variable objects you must put them in one of the UserFunctions, not in the Main window of the library.

When a variable is scoped as a Global, it is only used in the local program. It cannot be used in any Remote Function that is called.

  • When a library is imported, all variables declared (via Declare Variable objects) in the imported UserFunction are defined at that time for the scope specified. For example, if the variable is scoped as a Global, it can be accessed from any part of the program until the library is deleted. When a library is deleted, all variables declared in its UserFunctions are deleted as well.

See Also

About Variables, To Call a UserFunction in a Program


Agilent VEE Analysis Capabilities

VEE supports common math operations and hundreds of other functions. In addition, VEE also includes the MATLAB Script feature. The MATLAB Script feature is a subset of the standard full-featured MATLAB from The MathWorks. It provides additional mathematical capabilities in VEE including Signal Processing, advanced mathematics, data analysis, and scientific and engineering graphics. The MATLAB Script feature is fully integrated with VEE, and you can include MATLAB Script objects in any VEE program.

If neither VEE nor MATLAB have a math function you need, you still have several options available. You can create the function with the Formula object, you can write the function in a compiled language such as C and link it to VEE, or you can communicate with another software application from VEE.

See Also

Creating Expressions with the Formula Object

Using Built-In Math Objects

Using MATLAB Script in Agilent VEE


Creating Expressions with the Formula Object

To Create Expressions with the Formula Object

The Formula object can be used to write mathematical expressions in VEE. The variables in the expression are the data input pin names or global variables. The result of the evaluation of the expression will be put on the data output pin.

Following figure shows a Formula object. The input field for the expression is in the center of the object. A default expression (2*A+3) indicates where to enter the formula. Just double-click the field to type in a different expression.

note

You can type in a Formula expression on more than one line. If a Formula expression contains a Return, it is interpreted as a multi-line single expression. If a Formula contains statements separated by semi-colons (;), they are interpreted as multiple expressions in the Formula.

The Formula box is an Rich Text Format box and you can use standard editing commands to edit expressions in a Formula. For example, you can drag the mouse to highlight characters, use Ctrl-C for copying the characters, Ctrl-V for pasting, and Ctrl-X for deleting as well as using End, Insert, Delete, Backspace, etc. You also can use Code Completion and Code Insight in Formula box.

note

All the functions created from the Devices [image] Function & Object Browser Built-in type are simply Formulas that already have their expressions set appropriately. They can be modified to combine functions and add (or delete) inputs. You can also do multiple-line entry in the Formula object, and assign values to output terminals.

Evaluating an Expression with the Formula Object

In the next example, you will evaluate the expression, 2*A^6-B, where A=2 and B=1. (Notice the ^ sign for exponentiation.)

note

The variable names are not case-sensitive.

1 Select Device [image] Formula. Click the Formula input field and type 2*A^6-B.

2 Place the mouse pointer over the data input area (but not right over the A input) and press Ctrl-A to add an input pin.

note

It will be labeled B by default, but you can rename it.

3 Select Data [image] Constant [image] Int32, clone it by selecting Clone from the object menu, and connect the two Int32 objects to the Formula inputs A and B.

4 Enter 2 in the A Int32 input box and 1 in the B Int32 input box.

5 Select Display [image] AlphaNumeric and connect it to the output of Formula, and run the program. It should display the result 127.

Using an Agilent VEE Function in the Formula Object

This example generates a cosine wave and calculates the standard deviation and root mean square using the Formula object.

1 Select the Function Generator, Formula, and AlphaNumeric objects and connect them together using their data pins.

2 Clone the Formula object by opening the object menu and selecting Clone, and place it just below the first one. Connect the Function Generator data output pin to the second Formula object.

3 Clone another AlphaNumeric display and connect it to the second Formula object.

4 Enter sdev(A) in the first Formula object, and rms(A) in the second Formula object.

sdev(A) and rms (A) are the two math functions from the Device [image] Function & Object Browser tool window. Notice that they can be called as functions or independent objects, and they will perform in the same way.

5 Run the program. The program displays the same answers when these functions are put into the Formula object as it did when they were used as independent objects.

Now calculate the standard deviation and root mean square using only one Formula object. Formulas can have multiple output terminals with values assigned to them.

6 Double-click the object menu to Cut one of the Formula objects.

7 In the remaining Formula object, change the expression to
B=sdev(A);
C=rms(A)

note

When a Formula object contains multiple expressions, you must put a semicolon at the end of an expression to distinguish it from the next expression. For example, in the formula B=sdev(A); the semi-colon indicates the end of the expression.

NOte

You can put line breaks at any point in a Formula object. The formula is read as one expression as long as there are no semi-colons. For example, you could enter a single expression as

B=sdev
(A)

You can also add spaces in the formula to improve readability.

8 In the Formula object, add an output terminal. Rename the output terminals B and C. Connect output terminal B to one of the Alphanumeric objects, and output terminal C to the other Alphanumeric object.

9 Run the program. It should look like the following figure.

On Your Own

Complete the following exercises and check the results as follows.

1 Create an array of numbers from 1 to 2048 using the ramp object in the Generate category of Built-in Functions. Calculate the standard deviation of this array and display it.

2 Do the same exercise described in the previous step, using the ramp() function in a Formula object instead of the ramp object.

3 Do the same exercise described in the previous step by nesting the functions. Use only two objects.

For the second and third exercises, you have to delete the input terminal A on the Formula object to avoid an error message, because all data input pins must be connected and have data before an object can operate.

See Also

Formula

Copyright (c) 1991-2006 Agilent Technologies, Inc.


Using Built-In Math Objects

In the VEE Device [image] Function & Object Browser, you can access built-in (preprogrammed) mathematical expressions for both VEE and MATLAB.

Accessing a Built-in Operator or Function

To access VEE mathematical operators and functions, select Device [image] Function & Object Browser. For example, to create a formula that returns a random number in a specified range, select Built-in Functions => Probability & Statistics => random.

Notice that the Function & Object Browser displays a brief description of the current selection. You can also click on the Help button for a more detailed description of the current selection and get information such as the definition, use, syntax and examples.

To access MATLAB operators and functions, select Device [image] Function & Object Browser, then select MATLAB Functions. For example, to convert roots to polynomials, select MATLAB Functions => Interpolation & Polynomials => poly.

Again, a brief description of the current selection is displayed in the Function & Object Browser, and clicking on Help will display a more detailed description about the current selection. The MATLAB Runtime Engine and Script is discussed more in the section “Using MATLAB Script in Agilent VEE”.

Example: Calculating Standard Deviation

Generate a cosine waveform at a frequency of 1 kHz, amplitude of 1 V, a time span of 20 ms, represented by 256 points. Calculate its standard deviation and display it.

1. Select Device [image] Virtual Source [image] Function Generator. Set the Frequency appropriately and iconize it.

2. Select Device [image] Function & Object Browser, then select Built-in Functions, Probability & Statistics, and sdev. Click Create Formula.

note

You can go directly to the Function & Object Browser by pressing the fx icon on the tool bar or by pressing Ctrl-H.

3. Open the object menu for sdev() to consult Help.

note

The sdev(x) object is defined as the square root of the variance of x, and x may be of the type UInt8, UInt16, Int16, Int32, Int64, Real32, Real64, Coord, or Waveform. The Function Generator outputs a Waveform data type.

4. Connect the Function Generator to sdev(x).

5. Select Display [image] AlphaNumeric and connect it to the sdev(x) data output pin.

6. Run the program. It should look as follows.


To Display a Scalar Value

Use the AlphaNumeric object to display scalar values. This object clears itself and displays only the new data received each time it executes.

1. Add an AlphaNumeric display to the work area (Display [image] AlphaNumeric).

2. Connect the data input pin of the AlphaNumeric object to a source of scalar data (for example, a Real64 constant object).

3. Run the program to display the data.

Example

See also

To Display a Series of Values in a Log

AlphaNumeric


To Display an Array of Values

Use the AlphaNumeric object to display an array. This object clears itself and displays only the new data received each time it executes.

1. Add an AlphaNumeric display to the work area (Display [image] AlphaNumeric).

2. Connect the data input pin of the AlphaNumeric object to a source of array data (for example, an Alloc Real64 object)

3. Run the program to display the data.

4. Resize the AlphaNumeric object to show the entire array.

Example

The one-dimensional array is a single data container consisting of 10 elements.

See also

AlphaNumeric


To Display a Series of Values in a Log

Use the Logging AlphaNumeric object to display a series of values in a log. This object keeps a "history log" of the data it receives.

1. Add a Logging AlphaNumeric display to the work area (Display [image] Logging AlphaNumeric).

2. Connect the data input pin of the Logging AlphaNumeric object to a repeating source of data (for example, a For Count object).

3. Run the program to display the log of data.

Example

The Logging AlphaNumeric object displays a log of the 10 scalar values from the For Count object.

See also

To Show an Analog Display of Data

Logging AlphaNumeric


To Show an Analog Display of Data

Use an Indicator object to display scalar data on an analog indicator. These objects provide three-color range indication.

Fill Bar displays a value using a color bar.

Meter displays a value on an analog meter.

Tank displays a value using a color bar in a graphical tank.

Thermometer displays a value using "mercury" in a graphical thermometer.

The following procedures use the Thermometer object as an example. You can use similar techniques with the other Indicator objects.

To display data on a Thermometer

1. Add a Thermometer object to the work area (Display [image] Indicator [image] Thermometer).

2. Connect an Int32 Slider object to the data input pin of the Thermometer. Move the slider to select a value, and run the program. Run the program with the slider set to different values along its range.

The "mercury" level and color change as you change the slider value. The value is displayed at the bottom of the Thermometer.

3. Try changing the range of the Thermometer scale. Click on the lower range field (0) and enter a new value. Do the same for the upper range field (100). Note that the thermometer scale changes to conform to the new range.

To configure the Thermometer object

1. Click on Properties from the object menu of the Thermometer. The Thermometer Properties window appears.

2. Try changing a few parameters:

a. You can select either a vertical (the default) or a horizontal layout for the Thermometer. You can also turn the digital display on or off.

b. You can select a color for each range (low, mid, and high). Click on a color button to show the possible colors. You can also set the lower and upper limit values to determine where each color range begins.

3. Changes from the Properties window take effect immediately.

See also

To Show a Color Alarm

Fill Bar

Meter

Tank

Thermometer


To Show a Color Alarm

The Color Alarm object displays user-definable color indicator and text string depending on the value on its data input pin.

To use a Color Alarm

1. Add a Color Alarm object to the work area (Display [image] Indicator [image] Color Alarm).

2. Connect a Real64 Slider object to the data input pin of the Color Alarm. Move the slider to select a value, and run the program. Run the program with the slider set to different values along its range.

The color and text displayed by the Color Alarm change as you change the slider position.

To configure the Color Alarm

1. Click on Properties from the object menu of the Color Alarm object. The Properties window appears.

2. Try changing a few parameters:

a. From the Layout section of the dialog box you can select either a circular (the default) or a rectangular layout for the Color Alarm. You can also turn the digital display and the "three dimensional" border on or off.

b. From the Limits section of the dialog box you can select a color for each range (low, mid, and high). Click on a color button to show the possible colors. You can also change the text for each range, and you can set the lower and upper limit values to determine where each color range begins.

3. Changes made from the Properties window take effect immediately.

See also

To Show an Analog Display of Data

Color Alarm


To Display XY Values

The XY Trace and X vs Y Plot objects are usually the most applicable of the graphical displays.

To plot a series of values

1. Add an XY Trace object to the work area (Display [image] XY Trace).

2. Connect a source of data to the data input pin on the XY Trace object. The data can either be a continuously-generated series of points, or a waveform. The Function Generator object (Device [image] Virtual Source) works well for this example.

3. Run the program.

Example

In the following program, the For Range object repeats 37 times, generating the series of values 0, 10, 20, and so forth, up to 360. The Formula object calculates the sine of each value and outputs the result to the XY Trace object, which plots the resulting curve.

To plot a series of Y values against X values

1. Add an X vs Y Plot object to the work area (Display [image] X vs Y Plot).

2. Connect the XData and YData1 data input terminals to the appropriate sources of data. You can plot a continuously-generated series of Y points against X points, or you can plot a waveform against a waveform. However, you cannot mix data shapes.

3. Run the program.

Example

In the following program, the For Log Range object repeats 14 times, generating a logarithmic series of Y data points. The Counter outputs the current count to the XData input terminal, while the For Log Range object outputs the logarithmic series to the YData1 input terminal. The X vs Y Plot object displays the resulting curve.

See also

To Display a Waveform

X vs Y Plot

XY Trace


To Display a Waveform

Use the Waveform (Time) display object or the XY Trace object to display waveform data. Use the X vs Y Plot object to display one waveform against another. The following examples show how to display waveforms.

Note

To change the display objects’ properties such as layout, grid type, and markers, double-click on the title bar, or click on Properties on the object menu. For quick access to trace and scale properties, click on the trace and scale labels.

To display a sine wave on an XY Trace object

1. Add an XY Trace object to the work area (Display [image] XY Trace).

2. Add a Function Generator object to the work area (Device [image] Virtual Source [image] Function Generator). Connect the Func output of the Function Generator to the data input pin on the XY Trace object.

3. Change the settings on the Function Generator to output a 50 Hz sine wave, as shown below. Run the program.

In the following program, the XY Trace object displays the waveform in the time domain. The magnitude of the waveform is plotted against a time scale from 0 to 20m (20 milliseconds) to match the time span of the waveform. The XY Trace object does this automatically if the input data is a waveform. Otherwise, the X axis is simply the number of points plotted.

To display one waveform against another on an X vs Y Plot object

1. Add an X vs Y Plot object to the work area (Display [image] X vs Y Plot).

2. Add two Function Generator objects to the work area.

3. Connect the Func output of one Function Generator to the XData input pin on the X vs Y Plot object. Change the settings on this Function Generator to output a 50 Hz sine wave, with Phase set to 0 degrees.

4. Connect the Func output of the other Function Generator to the YData1 input pin. Change the settings on this Function Generator to output a 50 Hz sine wave, with Phase set to 45 degrees.

5. Run the program.

In the following program, the Function Generator objects generate two 50 Hz sine waves, which are 45 degrees out of phase. These waveforms are plotted against each other, displaying a classic Lissajous figure.

To display two waveforms on a Waveform (Time) object

1. Add a Waveform (Time) object to the work area (Display [image] Waveform (Time)).

2. Click on Add Terminal [image] Data Input... from the object menu to add a second terminal.

3. Add two Function Generator objects to the work area.

4. Connect the Func output of one Function Generator to the Trace1 input pin on the Waveform object. Change the settings on this Function Generator to output a 50 Hz sine wave, with Phase set to 0 degrees.

5. Connect the Func output of the other Function Generator to the Trace2 input pin. Change the settings on this Function Generator to output a 50 Hz sine wave, with a DcOffset of -0.8, and Phase set to 0 degrees.

6. Run the program.

In the following program, the Function Generator objects generate two 50 Hz sine waves, but the second has a d.c. offset of -0.8. The Waveform (Time) object displays the two waveforms as Trace 1 and Trace 2. To change the traces’ line-style properties, click on the trace labels, then change Line Type and Point Type in the dialog box that appears.

Note

You can also use the XY Trace, X vs Y Plot, and Waveform (Time) objects to display waveform data from an instrument.

See also

To Add a Trace

To Change the Line and Point Types of a Trace

Waveform (Time)

X vs Y Plot

XY Trace


To Display Polar Data

Use the Polar Plot display object to plot polar data. The following procedure is an example of how to use this object.

1. Add a Polar Plot display object to the work area (Display [image] Polar Plot).

2. Add a For Range object and a Formula object. Connect the objects as shown in the following program. Enter the desired trigonometric formula in the Formula object and run the program.

The trigonometric formula, 1-(sin(360-A)/3)-cos(A), creates the "heart-shaped" figure. You can enter any formula that you want. The For Range object repeats, stepping the angle one degree at a time from 0 to 360 degrees. The Polar Plot object plots the trigonometric data against the angle.

See also

Polar Plot


To Add a Trace

You can add a trace to any of the graphical (XY) display objects.

1. Select Add Terminal [image] Data Input from the object menu of the display object.

2. The new input is added to the object with the appropriate label. On some displays, only the pin is visible, not the labels.

3. To see the terminal labels, select Properties from the object menu and in Show Terminals select True.

4. Once you've added the terminals that you want, connect a source of data to each.

Note

A graphical (XY) display object can display as much as 255 traces.

See also

To Change the Color of a Trace

To Change the Line and Point Types of a Trace

Add traces to Graphs Programmatically


Add traces to Graphs Programmatically

To Add Traces to Graphs Programmatically

XY Trace, X vs Y Plot, Polar Plot, and Strip Chart can accept 2D array as Input Data, and display at most 12 traces at the same time. Multiple traces can be added into a graphical object programmatically.

To plot multiple traces

The following example shows how to display multiple traces in a Graph object.

1. Create a program like follows.

2. Select Properties from the object menu of the XY Trace object. The Properties window appears.

3. Under Behavior category, click on MatrixInput. Notice that the MatrixInput is false by default, change it to True.

4. After setting MatrixInput, run the program. Notice that two traces are displayed in the XY Trace graph.

More examples: 2dXyTrace.vee, MatrixInputStripChart.vee.

note

This MatrixInput property can be set to True only if there is no Next Curve Control Pin and the XY Trace has one single input data pin. Similarly, additional data inputs cannot be added to Matrix-Input graphs.

The MatrixInput property is not available in Panel View, and cannot be toggled at runtime programmatically.

The individual trace properties (colors, point-style, etc.) on all traces can be set at runtime.

See Also

To Add a Trace, XY Trace, X vs Y Plot, Polar Plot, Strip Chart


To Change the Color of a Trace

You can change the colors of the traces in the graphical (XY) display objects.

1. Click directly on the trace name in the display’s open view to change its properties.

2. In the Edit dialog box, click on the button beside Color. Click on a new color from the resulting dialog box, and click on OK.

3. After changing the trace color, click on OK in the Edit dialog box to return to the work area. The new color is now active.

4. Repeat these steps for each trace that needs a color change.

You can also edit these values from the Properties window. From the context menu of any XY display, select Properties. In the Properties window, scroll down to the Design category. Click on the "+" to the left of the desired Trace to view and edit the properties of that trace.

See also

To Change the Line and Point Types of a Trace


To Change the Line and Point Types of a Trace

You can change the line and point types of the traces in the graphical (XY) display objects.

1. Click directly on the trace name in the display’s open view to change its properties.

2. In the Edit dialog box, you can change both the line and point types:

a. To change the line type, click on the button to the right of Line Type: -- each time you click, the line type changes. Continue clicking until you find the line type you prefer.

b. To change the point type, click on the button to the right of Point Type: -- each time you click, the point type changes. Continue clicking until you find the point type you prefer.

3. After making the changes, click on OK to return to the work area.

4. Repeat these steps for each trace that needs new line and point types.

You can also edit these values from the Properties window. From the context menu of any XY display, select Properties. In the Properties window, scroll down to the Design category. Click on the "+" to the left of the desired Trace to view and edit the properties of that trace.

See also

To Change the Color of a Trace


To Zoom into or out of the Display

You can zoom into or out of the display in any of the graphical (XY) display objects. This procedure uses an example program to show how to use zoom.

1. Load the program manual23.vee from the manual examples directory (Help [image] Open Example...). Run the program to display a trace.

2. Select Zoom [image] In from the object menu of the display object.

3. Move the pointer to the upper right-hand corner of the area on which you want to zoom. Then click the left mouse button and drag the outline box to define the area.

4. Release the mouse button. The zoomed area is displayed.

5. Click on Auto Scale to return to the original display.

6. Now select Zoom [image] Out 2 X from the object menu of the display object.

7. Note how the display zooms out to twice its original size. Click on Auto Scale at any time to return to the original display.

Shortcut

Click the left mouse button and drag the outline box around the area you want to zoom, then release the button.


To Change the Grid Type

You can change the grid type of any of the graphical (XY) display objects.

1. Select Properties from the object menu. The Properties window appears.

2. On Grid Type, select the type of grid that you want (the default is Lines).

3. Changes made in the Properties window take effect immediately.


To Set Markers in the Display

You can set markers in any of the graphical (XY) display objects to identify the positions of peaks and valleys.

1. Select Properties from the object menu. The Properties window appears.

2. Under Markers category, select NumMarkers:

a. None turns markers off (the default).

b. One turns on one marker. The marker position is displayed at the bottom of the object.

c. Two turns on two markers. The position of each is displayed at the bottom of the object.

d. Delta turns on two markers. The position of each, and the difference between the two positions, is displayed at the bottom of the object.

In addition, if you change MarkerInterpolate to True, you can place the markers between the displayed data points. (The marker positions are calculated by linear interpolation.)

3. After setting Markers, you can move the markers along a trace by clicking and dragging on them with the mouse.

Example

A program containing markers is saved as manual24.vee in the Manual examples directory (Help [image] Open Example...).

1. Load and run the program to display a waveform on the XY Trace object.

2. Try moving the markers. Note the position data at the bottom of the XY Trace object.

See Also

To Get and Set Marker Properties, Programmatic Properties


To Get and Set Marker Properties

You can programmatically get and set marker values in any of the graphical (XY) display objects.

1. Assuming you have an XY display with markers, select Properties from the object menu. The Properties Window appears.

2. Type a name into the Declared Name field. This XYDisplay becomes a Local-to-Context variable, of type Object, with the name given. You can now refer to this XY Display in any Formula or expression by this name, just like any of other Declared Variable.

3. Get a Formula object (Device [image] Formula).

4. Type the desired expression into the Formula, separating the object name and the marker property with a period. For example: myGraph.marker1X

5. Delete the default input pin if you are not using it in your formula.

As an alternative to directly typing a formula, you can use the Function & Object Browser. Assuming you have a named XY display:

1. Select Device [image] Function & Object Browser

2. Select VEE Objects => XYDevice .

3. Select a marker property and click the Create Formula button. Modify the automatically-generated expression to change the default name "XYDevice" to the name you used for your XY display object.

See Also

To Set Markers in the Display, Programmatic Properties


To Automatically Re-Scale the Display

You can re-scale any of the graphical (XY) displays using various methods. In the Properties window, click on Scales, notice the Automatic Scaling property is on by default. This automatically rescales the display after receiving data. Also in Properties, in the Layout category, you can change ShowAutoScaleButton to True. This lets you manually rescale the display, if you turn Automatic Scaling off. Also, the object menu has an Auto Scale command. Usually, it is best to leave Automatic Scaling on.

Sometimes, you may prefer to programmatically turn Automatic Scaling on and off. To do this, add a control pin to the display object, and send it the correct information.

1. Select Add Terminal [image] Control Input from the object menu of the graphical display object.

2. Select the Scales control input.

3. Add a Record Constant object (Data [image] Constant [image] Record).

4. Enter the correct field names and values to control the Scales parameters, and connect its output pin to the Scales control input. Information about Scales parameters is available in the VEE Help topic for each display.

The following figure shows an example of this. The Record Constant sets the X scale’s maximum and minimum values, and turns Automatic Scaling off. It is important that the control input takes effect before data is sent to the display. To ensure this, the Record Constant sequence output pin is connected to the Function Generator sequence input pin.

See also

Record Constant

XY Trace


Customizing Test Data Displays

To Customize Test Data Displays

Displays may be customized in a variety of ways. Not only can you label, move, and size displays like all VEE objects, but you can also change the x/y scales, modify the traces, add markers, or zoom in on parts of the graphical display.

The following example illustrates some of these features. It uses the Noise Generator to generate a waveform, and then displays it with the Waveform (Time) display. The example also describes how to change the X scale, zoom in on a wave segment, and use the markers to measure the distances between points on the waveform. The same principles may be applied to all the graphical displays.

Displaying a Waveform

1 Select Device [image] Virtual Source [image] Noise Generator.

2 Select Display [image] Waveform (Time).

3 Connect the data output of the Noise Generator to the data input of Waveform (Time) and run the program.

Changing the X and Y Scales

1 Double-click the Waveform (Time) title bar to get the Y Plot Properties box, select the Scales folder, select 20m for the X Maximum and enter 1m.

This alters the time span of the display from 20 milliseconds to 1 millisecond.

2 Double-click the Minimum field on the Y axis where it says -1, and enter - .5. Click OK.

Zooming in on Part of the Waveform

1 Open the Waveform (Time) object menu and click Zoom [image] In.

The cursor becomes a small right angle. By clicking and dragging, you can draw a square on the graph outlining the area you want to enlarge.

2 Outline an area of the waveform including several peaks, and release the mouse button.

The display zooms in to this selected area of the waveform. Notice the x and y scales change automatically.

Adding Delta Markers to the Display

1 Move to the open view on the Noise Generator.

a Change the Num Points setting to 16. Run the program again.

b Open the Waveform (Time) object menu and select Properties (or just double-click on the title bar), then under Markers, click Delta. Then click OK.

note

You can get and set the values of the markers at runtime. See the online Help topic under Contents and Index [image] How Do I... Display Data for more information.

You will see two white arrows pointing up and down at one of the data points on the waveform. Also, notice that the display records the x and y coordinates of these markers at the bottom of the display. To measure the x or y distance between two peaks, click-and-drag the arrows to the peaks you want to measure. You will see one of the markers move to those new peaks with the new coordinates recorded at the bottom of the display

VEE will automatically interpolate between waveform data points. Open the object menu, select Properties, then under Markers, click MarkerInterpolate.

Changing the Color of the Trace

1 Double-click the title bar to get to Properties, then double click the Trace property.

You can select the Color, LineStyle, Name, and PointStyle properties for the Trace selected in this folder.

You can also change these values at run time by using the Traces or Scales control inputs.

2 The trace will now be displayed in the new color. Other display characteristics such as GridType may be customized in a similar fashion as the features in the exercise above.

note

VEE also includes Plot in the display object menus, which allows you to plot test results on the display without printing out the rest of the program.

See Also

Add trace to Graph Programmatically, Displaying Test Data


To Clear the Display

Use any of the following ways to clear the display on any graphical (XY) display object:

In the display object’s Properties window, change ClearAtPreRun to True in the Behavior category.

Select Clear Control [image] Display from the object menu.

Add a Clear control input terminal to the object. From the object menu, click on Add Terminal [image] Control Input. Select Clear and click on OK. The display is cleared whenever the Clear terminal is activated by a connection to a sequence output pin.


To Write Data to a File

Use the To File object to write data to a file.

To create a data file

1. Add a To File object to your program (I/O [image] To [image] File).

2. Connect the data input pin of the To File object to a source of data that you want to output to a file.

3. To change the name of the destination file, click on the To File button and enter a new file name in the dialog box. Then click on OK.

The To File object uses a write transaction to output the data to the file. VEE creates the file if it does not already exist.

To write data to a file

This procedure shows how to create a simple program that writes string and real data to a file. If your program requires different choices, then use this procedure as a guide.

1. Add a To File object to your program (I/O [image] To [image] File). Click on the checkbox to turn on Clear File At PreRun & Open (a check mark appears in the box).

In general, you'll want to turn on Clear File At PreRun & Open to ensure that the file is cleared and that no old data is in the file.

2. Double-click on <Double-Click to Add Transaction> to bring up the I/O Transaction dialog box.

3. Click on the DEFAULT FORMAT field (or its arrow). A drop-down menu appears.

4. Click on STRING FORMAT, and then click on OK. Now the modified transaction is WRITE TEXT a STR EOL. This transaction writes variable a (the data on input pin A) to myFile as text data in string format, followed by an end-of-line sequence (carriage-return/line-feed).

5. Double-click on <Double-Click to Add Transaction> to add a second transaction to the To File object (object menu [image] Add Trans…). The I/O Transaction dialog box appears.

6. Change the variable field (a by default) to b.

7. Click on the DEFAULT FORMAT field (or its arrow). The drop-down menu appears.

8. Click on REAL64 FORMAT, then click on OK. The second transaction is WRITE TEXT b REAL64 STD EOL. This transaction writes variable b as text in REAL64 STD format to myFile.

9. Connect a Text constant object to terminal a and a Real64 constant object to terminal b. The finished program should appear as follows:

When you run the program, two lines of data are written to myFile, each followed by an end-of-line sequence (carriage-return/line-feed). The first is the string String data. The second is the real number 3.142.

See also

To Read Data from a File

To Edit a File I/O Transaction

To Select a File Name Programmatically

To DataSet

To File


Using the To/From File Objects

To Use the To/From File Objects

The To File and From File objects read data to and from files based on I/O transactions. They have the following characteristics:

• A data file is opened on the first READ or WRITE transaction. When the program ends, VEE closes any open files automatically.

• VEE maintains one read pointer and one write pointer per file regardless of how many objects are accessing the file. The read pointer identifies the next data item to be read, and the write pointer indicates where the next data item should be written.

• The To/From File objects can append data to existing files or overwrite them. If the Clear File at PreRun & Open setting is checked in the open view of the To File object, then the write pointer starts at the beginning of the file. If not, the pointer is positioned at the end of the existing file. Each WRITE transaction appends information to the file at the location of the write pointer. If an EXECUTE CLEAR transaction is performed, the write pointer moves to the beginning of the file and erases its contents.

• A read pointer starts at the beginning of a file, and advances through the data depending on the READ transactions. You may perform an EXECUTE REWIND in the From File object to move the pointer back to the beginning of the file without affecting any data.

See Also

Understanding I/O Transactions

Lab 5-3: Using the To/From File Objects

Lab 2-3: Using Data Files


To Read Data from a File

Use the From File object to read data from a file.

This procedure is a companion to the procedure To Write Data to a File. It shows how to read string and real data from the file created in that procedure. If your program requires different choices than those presented here, then use this procedure as a guide.

1. Add a From File object to the program (I/O [image] From [image] File).

2. Change the default transaction to READ TEXT x STR using the I/O Transaction dialog box as described for writing to a file.

3. Add a second transaction READ TEXT y REAL64, again using the I/O Transaction dialog box as described for writing to a file.

4. Connect AlphaNumeric displays to both outputs (X and y).

5. Connect the sequence output pin of the To File object to the sequence input pin of the From File object. This ensures that data is written to myFile before the From File object attempts to read data from the file. The finished program should appear as follows:

See also

To Edit a File I/O Transaction

To Select a File Name Programmatically

To Write Data to a File

From DataSet

From File


To Edit a File I/O Transaction

The To File object uses a write transaction to communicate with the specified data file. The default transaction is WRITE TEXT a EOL, which writes the data on input A as text, followed by an end-of-line sequence (a carriage-return/line-feed by default). The From File object uses similar transactions to read data from a file. You can edit a transaction by using the I/O Transaction dialog box.

To edit a transaction

1. Double-click on the transaction field in the To File or From File object. The I/O Transaction dialog box appears.

2. To change the action, click on WRITE or READ, select an action.

3. To change the encoding, click on Text, then select the encoding.

In general, the container encoding is useful if you want to retrieve the data back into VEE using From File, but not if you want to access the data file with an external application such as a spreadsheet program.

The dialog box adapts to the entries you select, making corresponding options available.

4. Change other field entries as needed to configure various options such as the data format, and the end-of-line sequence, then click on OK.

5. To add another transaction, double-click on the blank line below the last transaction.

See also

From File

To File

Understanding I/O Transactions


To Store and Retrieve a Waveform

Waveform data is best stored and retrieved in the form of a data container. The basic procedure is as follows:

1. Use a WRITE CONTAINER transaction in the To File object to write the waveform data to a file.

2. Use a READ CONTAINER transaction in the From File object to read the waveform data back from the file.

Example

The program manual20.vee in your manual examples directory shows how to use waveform data. The program works as follows:

1. The waveform data from the Function Generator is written to the wavedata file by the To File object using a WRITE CONTAINER a transaction.

2. The data is read back from the wavedata file as a waveform container by From File using a READ CONTAINER x transaction. The data is output on terminal X, and displayed by the Waveform (Time) display.

3. The sequence pin connections ensure that the waveform is written to the file before From File attempts to read it.

In a more typical situation, one VEE program would store the waveform data into a file, and then a second VEE program would read the data back into VEE, analyze it, and display it.

See also

To Write Data to a File

To Read Data from a File

To Edit a File I/O Transaction

From File

To File


To Select a File Name Programmatically

If your program reads or writes data using objects such as From File or To File, you can set up your program to request a file name at run time. The following example uses the File Name Selection dialog object with To File to show how this works.

1. Add a To File object (I/O [image] To [image] File).

2. Click on Clear File At PreRun & Open. Double-click on <Double-Click to Add Transaction>, and click on OK.

3. Add a File Name control input terminal to the To File object. (Object menu [image] Add Terminal [image] Control Input, click on OK.)

4. Add a File Name Selection object (Data [image] Dialog Box [image] File Name Selection) to the work area and connect its File Name output to the File Name control pin on the To File object. Add a Stop object to the Cancel output.

5. Connect the sequence output pin of the File Name Selection object to the sequence input pin of the To File object. This ensures that the To File object will not operate until a file name has been selected.

6. In the File Name Selection object, change the Select File For field to Writing. This ensures that the user is alerted before an existing file is overwritten.

7. Add a Text object, and connect it to pin a of To File.

Example for Windows

When you run the program, the Enter File Name dialog box appears, prompting for a file name. Enter a new file name or click on an existing file name. In Windows, change the Save as type entry to All Files (*.*) since the file to be saved is not a program file. Click on Save.

See also

File Name Selection

From File

To File


To Store Data for a Spreadsheet Program

You can use VEE file I/O to produce a data file that can be read by a spreadsheet program such as Microsoft Excel or Lotus 1-2-3. In general, the steps are as follows:

1. Determine what data file format the spreadsheet program requires. For example, how are rows and columns delimited?

2. Create a VEE program that collects the data, and then outputs the data to a file in an ASCII text format using the appropriate delimiters. Normally, the To File object is the best way to do this.

Example

The program manual21.vee in your manual examples directory shows how to collect (or simulate) 10 voltage readings, each with a time stamp, and output the data to a file that can be read by Microsoft Excel. The program works as follows:

1. The For Count and Delay objects trigger the following events approximately every 10 seconds:

a. The Counter object advances by 1.

b. The Now object outputs the current time (to within 1 second), which is converted to the Time Stamp format by the To String object.

c. The dmm (hp34401a @ (NOT LIVE)) instrument panel simulates a reading from a HP 34401A Multimeter.

2. The Build Record object builds a record for each reading (every 10 seconds), as follows: field Cnt is the count or test number, field Tm is the current time for the reading (in the format hh:mm:ss), and field Vlts is the simulated voltage reading returned by the instrument panel object.

3. The To File object writes the data out to a file in text form. In the transaction WRITE TEXT a.Cnt," ",a.Tm," ",a.Vlts EOL

a.Cnt represents "field Cnt of record a" (the count),

" " inserts a space (as a delimiter),

a.Tm represents "field Tm of record a" (the time),

" " inserts another space (as a delimiter),

a.Vlts represents "field Vlts of record a" (the reading), and

EOL inserts the end-of-line sequence (carriage-return/line-feed).

Thus, each record is converted to string format and output (with spaces as delimiters) in the following format:

1 11:29:06 5.687753697513882

When the program is finished, the file myfile will consist of 10 rows of data, for example:

1 11:29:06 5.687753697513882

2 11:29:16 6.437091378803515

3 11:29:26 7.064658105870967

4 11:29:36 7.439572075814199

5 11:29:46 7.465490768920665

6 11:29:56 7.135229243023529

7 11:30:06 6.53525004955898

8 11:30:16 5.795432812581498

9 11:30:26 6.154398687554457

10 11:30:36 6.844467171462198

In each row, the first field (the count) is followed by a space (the delimiter), the second field (the time) is followed by another space, and the third field (the reading) is followed by an end-of-line sequence.

The output file will be a Windows ASCII file, which can be read directly into Microsoft Excel. Just open the file from Excel and, when asked, tell Excel that the file is delimited, and that the delimiter is the space.

The data should appear as follows in the Excel spreadsheet:

By using appropriate delimiters you can create files that can be read by a variety of spreadsheet programs.

You can automate the process by using ActiveX Automation and Controls, or DDE (Dynamic Data Exchange). ActiveX is more powerful than DDE when you want to control other applications from VEE. Refer to Using ActiveX Automation in VEE, Using an ActiveX Control in VEE, and Communicating With Programs for information about using ActiveX and DDE.

See also

To Collect Data into a Record

Build Record

To DataSet

To File


To Add Objects to the UserObject Work Area

Any object that you place inside the work area of a UserObject edit window becomes part of the UserObject. Use any of the following methods:

Select the appropriate object from the menus and place the object in the UserObject.

Move an object from the Main work area to the UserObject.

Use Cut/Copy/Paste to place an object that is highlighted in the Main work area into the UserObject.

Clone an object in the Main work area, moving the clone into the UserObject.

See also

UserObject


To Add Input and Output Terminals to a UserObject

In general, you can add input and output terminals to a UserObject edit window using the same techniques that you would for any other object. The terminals also appear on the UserObject icon as you add them to its edit window.

Using the object menu

From the object menu, select Add Terminal, and then select the type of terminal you want to add: Data Input, Control Input, Data Output, or Error Output. You can use this method to add terminals directly to the UserObject icon or the associated edit window.

Using the mouse and keyboard

To add a data input terminal, place the mouse cursor in the data input terminal area and press Ctrl+A. A data input terminal is added to the UserObject at the cursor location each time you press Ctrl+A.

To add a data output terminal, place the mouse cursor in the data output terminal area and press Ctrl+A. A data output terminal is added to the UserObject at the cursor location each time you press Ctrl+A.

Note

To delete terminals, place the mouse cursor over the terminal area and press Ctrl+D.

See also

UserObject


To Create a UserObject in a Program

The following example shows, step-by-step, how to create a simple UserObject and connect it in a VEE program. Ideally, the objects used together in a UserObject should perform a particular task.

1. Add a UserObject to the Main work area (Device [image] UserObject). A UserObject icon appears. Double-click on the icon to open the UserObject edit window.

2. Add objects to the UserObject work area, and connect the terminals between them as needed.

3. Add and connect the input and output terminals for the UserObject:

a. Place the mouse cursor in the input terminal area of the UserObject and press Ctrl+A. The data input terminal appears in the edit window’s terminal area and on the input side of the UserObject icon.

b. In the edit window, connect the inside pin of the input terminal to the appropriate object inside the UserObject.

c. Place the mouse cursor in the output terminal area of the UserObject and press Ctrl+A. The data output terminal appears in the edit window’s terminal area and on the output side of the UserObject icon.

d. In the edit window, connect the inside pin of the output terminal to the appropriate object inside the UserObject.

e. In the Main Window, connect an external object to the input terminal on the UserObject icon to send data to the UserObject.

f. In the Main Window, connect an external object to the output terminal on the UserObject icon to send data from the UserObject.

4. Change the UserObject title to a descriptive name so you can identify it in the program. Double-click the title bar on the UserObject edit window. In the Properties Window, type in a new title.

5. Run the program to test the UserObject.

The following example shows a program with the UserObject edit window open.

See also

To Add Input and Output Terminals to a UserObject

To Build a UserObject Panel

UserObject


To Create a UserObject from Objects in a Program

Once you have written a VEE program you may decide that you want to make part of the program into a UserObject. This procedure uses an example program to show how to convert several objects in a program into a UserObject.

1. Open the program manual13.vee in your manual examples directory (Help [image] Open Example...). This program changes fields in a record.

2. Select the objects: Set Name Field, and Set Empl_no Field.

To select objects, press and hold the Ctrl key, then click on each object using the left mouse button. The objects are highlighted with shadows when selected.

3. When you are done selecting objects, select Edit [image] Create UserObject. In the Create UserObject dialog box, change the title to Change Record Fields, then click OK.

The new UserObject appears as an icon view in the Main Window and contains all of the terminal connections to the objects inside the UserObject. The UserObject edit window also appears so you can make changes.

4. Run the program.

The following example shows the program with the UserObject edit window open.

See also

To Build a UserObject Panel

UserObject


To Exit a UserObject Early

Normally, a UserObject (or UserFunction) will not complete execution and propagate data on its output terminals until every object inside it has completed execution; however, there are two objects that force propagation to exit a UserObject before all of the objects within the UserObject have operated.

Exit UserObject, when activated, causes an immediate exit from the UserObject context to the context outside it (for example, the Main program).

Raise Error generates a user-defined error message box, and also causes propagation to exit the UserObject. (No data is output from the UserObject unless there is an Error output pin.)

Example

The following procedure shows how to use Exit UserObject using an example program:

1. Open manual26.vee from your manual examples directory (Help [image] Open Example...). Double-click on the Add Random Number object to open the UserObject edit window, then arrange the Main Window and UserObject edit window so you can see all of the objects.

2. To see the order of propagation, turn on Show Data Flow and Show Execution Flow using the toolbar buttons.

3. Run the program. In Add Random Number, the OK and Cancel buttons both become active when the program is run, pausing execution in the UserObject. (The Cancel button is just an OK button with the title changed.) Pressing the buttons cause the following actions:

OK: The upper thread in the UserObject finishes propagating. The A+B object adds its two inputs, the result is propagated to output terminal X, and then the Exit UserObject is activated. The result on terminal X is output to the AlphaNumeric display as the UserObject exits.

Cancel: The Exit UserObject in the lower thread operates. This causes an exit from the UserObject without finishing propagation of the upper thread. No data is output.

See also

Exit UserObject

Raise Error

UserObject


To Create and Use a Library of UserObjects

You can save one or more UserObjects in a file to reuse in other programs.

To create a UserObject library

1. Create the UserObject(s) in your work area.

2. Select the UserObject(s).

3. Select File [image] Save Objects. You'll be prompted for a file name in which to save the UserObject(s).

To use a UserObject library

1. Select File [image] Merge. You'll be prompted for a file name.

2. Select the file name for your library. The UserObject(s) in the file are merged into the work area. Place them where you want them in your program.

See also

To Add Objects to the UserObject Work Area

To Add Input and Output Terminals to a UserObject

To Create a UserObject in a Program

To Create a UserObject from Objects in a Program


To Secure a UserObject

After the design of a UserObject is final, you may want to save a secured version of it. You can then let others add the UserObject to their programs, while preventing them from viewing the contents or changing the UserObject. There are no side-effects to the original UserObject.

1. In the UserObject edit window, select Save Secured Version from the object menu.

2. You will be prompted for a file name in which to save the secured version of the UserObject. Enter a descriptive file name. The .vee file name extension is added automatically.

3. Click on Save.

To use the secured UserObject in a program, use File [image] Merge. You'll be prompted for the file name.

Tips

If the UserObject does not have a panel view, the secured version is displayed as an icon. The icon can be restored to its open view, but the details inside are not visible (except for the terminals). No one can view or edit the contents.

If the UserObject has a panel view, the secured version is displayed as an icon. The icon can be restored to its open view, but only the panel view and the terminals are visible. The detail view is not visible, and the panel view cannot be modified.


To Create a UserFunction in a Program

The following example shows, step-by-step, how to create a simple UserFunction and connect it in a VEE program. Ideally, the objects used together in a UserFunction should perform a particular task.

1. Add a UserFunction to the Main work area (Device [image] UserFunction). A UserFunction edit window appears.

2. Add objects to the UserFunction work area, and connect the terminals between them as needed. You can use the same techniques to add objects to a UserFunction as described in To Add Objects to the UserObject Work Area.

3. Add and connect the input and output terminals for the UserFunction:

a. Place the mouse cursor in the input terminal area of the UserFunction and press Ctrl+A. The data input terminal appears in the edit window’s terminal area.

b. In the edit window, connect the inside pin of the input terminal to the appropriate object inside the UserFunction.

c. Place the mouse cursor in the output terminal area of the UserFunction and press Ctrl+A. The data output terminal appears in the edit window’s terminal area.

d. In the edit window, connect the inside pin of the output terminal to the appropriate object inside the UserFunction.

4. Change the UserFunction title to a descriptive name so you can identify it in the program. Double-click the title bar on the UserFunction edit window. In the Properties Window dialog box, type in a new title. The title cannot contain spaces.

5. Add a Call object to your program. In the UserFunction edit window’s object menu, click on Generate [image] Call. A Call object appears with the title and terminals corresponding to those added to the UserFunction.

Depending on the UserFunction’s purpose, you may want to generate a call to it from one of the other objects in the Generate menu.

6. Connect lines to the input and output terminals on the Call object.

7. Run the program to test the UserFunction.

The following example shows a program with the UserFunction edit window open.

See Also

To Build a UserFunction Panel

To Call a UserFunction in a Program

To Create a UserFunction from Objects in a Program

To Edit a UserFunction

UserFunction

Refer to Help => Contents and Index => Tell me about...=> User-Defined Functions


To Create a UserFunction from Objects in a Program

Once you have written a VEE program you may decide that you want to make part of the program into a UserFunction. This procedure uses an example program to show how to convert several objects in a program into a UserFunction.

1. Open the program manual13.vee in your manual examples directory (Help [image] Open Example...). This program changes fields in a record.

2. Select the objects: Set Name Field, and Set Empl_no Field.

To select objects, press and hold the Ctrl key, then click on each object using the left mouse button. The objects are highlighted with shadows when selected.

3. When you are done selecting objects, select Edit [image] Create UserFunction. In the Create UserFunction dialog box, change the title to ChangeRecordFields, then click OK. UserFunction titles cannot contain spaces.

Two changes occur in the program. The objects are collected into the new UserFunction, and appear in a UserFunction edit window so you can make changes. A Call object appears in the Main Window. All terminal connections are retained.

4. Run the program to test the UserFunction.

The following example shows the program with the UserFunction edit window open, and the Call object in its open view.

See also

To Build a UserFunction Panel

To Call a UserFunction in a Program

To Create a UserFunction in a Program

To Edit a UserFunction

UserFunction

Refer to Help => Contents and Index => Tell me about...=> User-Defined Functions


To Edit a UserFunction

To edit a UserFunction, the VEE program containing the UserFunction must be open. Then you can change how the function operates in the UserFunction edit window.

To edit a UserFunction

1. Open the program containing the UserFunction you want to edit.

2. Select Edit [image] Edit UserFunction. The Edit UserFunction dialog box appears with a list of all of the UserFunctions in that program.

3. Select the name of the UserFunction you want to edit, and click on OK. The UserFunction edit window appears.

4. Make your changes in the edit window’s work area.

5. Close the edit window. Any changes that you have made will affect all calls to the UserFunction.

Shortcuts

Get the Edit [image] Edit UserFunction menu pick by moving the mouse pointer to an empty space in the work area, then clicking the right mouse button.

Select Edit UserFunction from the object menu of the Call object, which opens the called function’s edit window.

In the Program Explorer, double-click on the UserFunction’s name to open its edit window.

See also

To Call a UserFunction in a Program

To Create a UserFunction in a Program

To Create a UserFunction from Objects in a Program

UserFunction

Calling a UserFunction from an Expression

Creating a UserFunction Library


To Call a UserFunction in a Program

Once you have created a UserFunction, you can call it multiple times within a VEE program. This topic uses an example program to show how to call UserFunctions.

Open the program manual51.vee in your manual examples directory (Help [image] Open Example...). This program contains the RandomArray UserFunction, which is called three times:

The Call object calls RandomArray and outputs the returned array.

The Formula object calls RandomArray in the expression 1+RandomArray(). The expression adds 1 to each element of the returned array.

The To File object calls RandomArray in the transaction WRITE CONTAINER RandomArray(). The transaction writes the array returned by RandomArray to the file myFile as a container. The From File object reads the data file and sends the results to the display.

Tips

You can call the RandomArray UserFunction as many times as you like within a program.

Each call of a UserFunction is independent. (In this example, each call to RandomArray generates a different set of random numbers.)

In the Call object, just specify the name of the function to call (for example: RandomArray). However, if you call the UserFunction from an expression, you must use the expression syntax, for example: RandomArray().

UserFunction names are case-insensitive.

UserFunction names must be unique.

You can call a UserFunction name from objects that use expressions, such as the If/Then/Else, To File, and Sequencer objects.

See also

To Create a UserFunction in a Program

To Create a UserFunction from Objects in a Program

To Edit a UserFunction

UserFunction

Sequencer Object

Help => Contents and Index => Tell me about...=> User-Defined Functions


Calling a UserFunction from an Expression

To Call a UserFunction from an Expression

You can call a UserFunction from an expression in a Formula object or from any expression evaluated at run time, such as from a ToFile object. This program demonstrates several ways to call a UserFunction.

In the program, the Call object calls the UserFunction noiseUF and returns a sine wave with an added noise component. The expression abs(noiseUF(Y)) in the first Formula object returns the absolute value of the waveform returned by the UserFunction. Thus, the displayed noisy sine wave is rectified in the positive direction.

The expression abs(noiseUF(Y))-1.5 in the second Formula object also calls the UserFunction but adds a negative dc offset to the waveform. The sequence pins are used to ensure correct propagation because the UserFunction uses the global variable.

This program is saved in the file manual43.vee in the examples directory.

See Also

About UserFunctions, Calling a UserFunction from an Expression, Converting Between UserObjects and UserFunctions, Creating a UserFunction Library, Importing and Calling a UserFunction, Using a Library of Functions


Converting Between UserObjects and UserFunctions

To Convert Between UserObjects and UserFunctions

To convert a UserObject into a UserFunction, select Make UserFunction from the UserObject's object menu. The UserObject window is replaced by a UserFunction window with the same input and output terminals. The UserObject object is replaced by a UserFunction Call object.

To reconvert the UserFunction back into a UserObject , select Make UserObject from the object menu of the UserFunction window. Any calls to the UserFunction remain (you will have to manually delete them), but the UserFunction is automatically converted into a UserObject .

See Also

About UserFunctions, Calling a UserFunction from an Expression, Converting Between UserObjects and UserFunctions, Creating a UserFunction Library, Importing and Calling a UserFunction, Using a Library of Functions


Using a Library of Functions

ToUse a Library of Functions

Methods for creating each type of user-defined function and using it in a VEE program are similar. All these functions are called using the Call object or from certain expressions, such as in Sequencer or Formula objects. You can use any of the three kinds of user-defined functions in a library. To use a library of functions, follow these steps:

1 Import the library.

Use the Device [image] Import Library object. Select the Library Type (UserFunction, Compiled Function, or Remote Function) and fill in the appropriate fields. Specific information about these fields is explained in the associated section in this chapter.

2 Call one or more functions that are contained in the library.

Use the Call, Formula, or Sequencer objects from the Device menu. You can also use other objects that call expressions at run time, such as If/Then/Else or To File. If you want to have multiple values returned from the function, you must use a Call object.

3 Delete the library.

If memory management or program execution speed is a concern, use the Device [image] Delete Library object to programmatically free the library from memory. Otherwise, libraries are automatically deleted when VEE exits.

The ability to call a UserFunction from an expression is very useful — especially when you include such an expression in a transaction in the Sequencer object. See Help => Contents and Index => How do I => Use Sequencer Objects for more information about this topic.

See Also

Creating a UserFunction Library, About Compiled Functions, About Remote Functions

About UserFunctions, Calling a UserFunction from an Expression, Converting Between UserObjects and UserFunctions, Creating a UserFunction Library, Importing and Calling a UserFunction, Using a Library of Functions


Creating a UserFunction Library

To Create a UserFunction Library

Except local UserFunctions that are created and used within the same program, you can also create a library of multiple UserFunctions stored externally and later imported into a program.

To create a library of UserFunctions , create the UserFunctions in the empty VEE work area and save them to a file. For example, to create a library of two UserFunctions , myRand1 and myRand2 (which add random numbers to an input value), create the two UserFunctions as follows.

To create a UserFunction library, save the program with a name that identifies it as a library. For example, use a .vlb extension instead of .vee.

note

Normally, the program should contain only UserFunctions . If other objects are in the program (e.g., in Main), they are ignored when the library is imported. If you use Declare Variable objects, put them in one of the UserFunctions, not in the Main window of the library.

See Also

About UserFunctions, Calling a UserFunction from an Expression, Converting Between UserObjects and UserFunctions, Creating a UserFunction Library, Importing and Calling a UserFunction, Using a Library of Functions


Importing and Calling a UserFunction

To Import and Call a UserFunction

To import the UserFunction library into a program, use the Import Library object. The following program imports the library from the file user_func_lib and calls the UserFunctions myRand1 and myRand2.

The Import Library object allows you to specify a type of library: UserFunction, Compiled Function, or Remote Function. If you select UserFunction, you also specify a Library Name and File Name.

The Library Name field specifies a local name for the library within the program. This makes it possible for the Delete Library object to delete the library from the program. In this case, Import Library attaches the name myLib to the library imported from the file user_func_lib.

The File Name field specifies the file from which to import the library, user_func_lib in this case. If you click on the File Name field you can select from a list of all library files.

This program is simple so it is not necessary to delete the UserFunction library after it is used. In a large program with calls to large libraries, deleting a library when you no longer need it reduces the program’s memory requirements.

note

You cannot edit UserFunctions imported with Device [image] Import Library, but you can view their contents and set breakpoints for debugging. To view imported UserFunctions, use the Program Explorer.

You can merge a library of UserFunctions using File [image] Merge Library. Once the library is merged into your program, you can edit the individual UserFunctions with Edit [image] Edit UserFunction.

See Also

About UserFunctions, Calling a UserFunction from an Expression, Converting Between UserObjects and UserFunctions, Creating a UserFunction Library, Importing and Calling a UserFunction, Using a Library of Functions


Using a Compiled Function

To use a Compiled Function, you:

1 Write the external program.

2 Create the DLL and a definition file.

3 Import the library and call the function from VEE.

4 Delete the library from VEE memory when you are done.

The methods for importing a Compiled Function library and for calling the function are very similar to those for UserFunction libraries. The Import Library object attaches the DLL to the VEE process and parses the definition file declarations.

The definition file defines the type of data passed between the external library and VEE. (This file is discussed later in this section.) The Compiled Function can then be called with the Call object or from such objects as Formula and If/Then/Else.

See Also

Overview of Compiled Functions, The Definition File, Importing and Calling a Compiled Function, Building a C Function, Creating a Dynamic Link Library, Using Dynamic Link Libraries


Building a C Function

To Build a C Function

The following C function accepts a real array and adds 1 to each element in the array. The modified array is returned to VEE on the Array terminal, while the size of the array is returned on the Ret Value terminal. This function, once linked into VEE, becomes the Compiled Function called in the VEE program as follows.

/*

   C code from manual49.c file

*/

#include <stdlib.h>

#ifdef WIN32

# define DLLEXPORT __declspec(dllexport)

#else

# define DLLEXPORT

#endif

/* The description will show up on the Program Explorer when you select "Show Description" from the object menu and the Function Selection dialog box in the small window on the bottom of the box.

*/

DLLEXPORT char myFunc_desc[] = "This function adds 1.0 to the array passed in";

DLLEXPORT long myFunc(long arraySize, double *array) {

   long i;

   for (i = 0; i < arraySize; i++, array++) {       *array += 1.0;    }

   return(arraySize);

}

The definition file for this function is:

   /*

   definition file for manual49.c

   */

   long myFunc(long arraySize, double *array);

(This definition is the same as the ANSI C prototype definition in the C file.)

You must include any header files on which the routine depends. The library should link against any other system libraries needed to resolve the system functions it calls.

The example program uses the ANSI C function prototype. The function prototype declares the data types that VEE should pass into the function.

The array has been declared as a pointer variable. VEE will put the addresses of the information appearing on the Call data in terminals into this variable. The array size has been declared as a long integer. VEE will put the value (not the address) of the size of the array into this variable. The positions of both the data input terminals and the variable declarations are important. The addresses of the data items (or their values) supplied to the data input pins (from top to bottom) are placed in the variables in the function prototype from left to right.

One variable in the C function (and correspondingly, one data input terminal in the Call object) is used to indicate the size of the array. The arraySize variable is used to prevent data from being written beyond the end of the array. If you overwrite the bounds of an array, the result depends on the language you are using. In Pascal, which performs bounds checking, a run-time error will result, stopping VEE. In languages like C, where there is no bounds checking, the result will be unpredictable, but intermittent data corruption is probable.

This example has passed a pointer to the array so it is necessary to dereference the data before the information can be used.

The arraySize variable has been passed by value so it will not show up as a data output terminal. However, here we have used the function's return value to return the size of the output array to VEE. This technique is useful when you need to return an array that has fewer elements than the input array.

The following program calls the Compiled Function created from the example C program:

The above example is saved in the file manual49.vee in the examples directory. The C file is saved as manual49.c, the definition file as manual49.h and the shared library as manual49.sl.

See Also

Overview of Compiled Functions, The Definition File, Using a Compiled Function, Importing and Calling a Compiled Function, Creating a Dynamic Link Library, Using Dynamic Link Libraries

A user-defined function created by dynamically linking a program, written in a programming language such as C, into the VEE process. The user must create a DLL (Dynamically Linked Library) file and a definition file. The Import Library object attaches the DLL to the VEE process and parses the definition file declarations. The Compiled Function can then be called with the Call Function object, or from certain expressions. See also UserFunction and Remote Function.


Creating a Dynamic Link Library

To Create a Dynamic Link Library

VEE provides access to DLLs through the Call object and through Formula objects.

note

This section describes how to call a DLL, not how to write a DLL. VEE Version 3.2 and greater only calls 32-bit DLLs, not 16-bit DLLs.

Creating the DLL

Create the DLL before writing the VEE program. Create the DLL as you would any other DLL, except that only a subset of C types are allowed. (See “Creating the Definition File".)

Declaring DLL Functions If you are using Microsoft Visual C++ Version 2.0 or greater, the function definition should be:

   __declspec(dllexport) long myFunc (...);

This definition eliminates the need for a .DEF file to export the function from the DLL. Use the following command line to compile and link the DLL:

   cl /DWIN32 $file.c /LD

/LD creates a DLL. Use /Zi to generate debug information.

The MS linker links to the C multi-threaded Runtime Library by default. If you use functions like GetComputerName(), you need to link against Kernel32.lib. The compile/link line would look like:

   cl /DWIN32 file.c /LD /link Kernel32.lib

Declaring DLL Functions To work with VEE, DLL functions can be declared as __declspec(dllexport) using Microsoft C++ version 2.0 or greater. This eliminates the need for a .DEF file. For example, a generic function could be created as follows:

__declspec(dllexport) long genericFunc(long a) {return (a*2); }

If you are not using Microsoft Visual C++, the .DEF file contains:

   EXPORTS genericFunc

And the function definition looks like:

   long genericFunc(long a);

Creating the Definition File The definition file contains a list of prototypes of the imported functions. VEE uses this file to configure the Call objects and to determine how to pass parameters to the DLL function. The format for these prototypes is:

<return type> <modifier> <function name> (<type> <paramname>, <type> <paramname>, ...) ;

where:

• <return type> can be: byte, int, short, long, int64, float, double, char*, VEE_BOOL, or void.

• <function name> can be a string consisting of an alpha character followed by alphanumeric characters, up to a total of 512 characters.

• <modifier> can be _cdecl, _pascal, or _stdcall.

• <type> can be: byte, int, short, long, int64, float, double, VEE_BOOL, byte*, int*, char*, short*, long*, int64*, float*, double*, char**, VEE_BOOL*, or void.

• <paramname> can be a string consisting of an alpha character followed by alphanumeric characters, up to a total of 512 characters. The parameter names are optional, but recommended. If a parameter is to be passed by reference, the parameter name must be preceded by the indirection symbol (*).

For example:

Pass in four parameters, return a long:

   long aFunc(double *,long param2,long *param3, char *);

No input parameters, return a double:

   double aFunc();

Pass in a string, return a long:

   long aFunc(char *aString);

Pass in an array of strings, return a long:

   long aFunc(char **aString);

Parameter Limitations

A DLL function called from VEE pushes a maximum of 144 bytes on the stack. This limits the number of parameters used by the function. Any combination of parameters may be used as long as the 144-byte limit is not exceeded. A long uses four bytes, a double uses eight bytes and a pointer uses four bytes. For example, a function could have 36 longs, or 18 doubles, or 20 pointers and 8 doubles.

The Import Library Object

Before you can use a Call object or Formula box to execute a DLL function you must import the function into the VEE environment via the Import Library object. On the Import Library object, select Compiled Function under Library Type. Enter the correct definition file name using the Definition File button. Finally, select the correct file using the File Name button. The Library Name button assigns a logical name to a set of functions and does not need to be changed.

The Call Object

Before using a DLL function with the Call object you must configure the Call object. The easiest way to do this is to select Load Lib on the Import Library object menu to load the DLL file into the VEE environment. Then, select Select Function on the Call object menu.

VEE will bring up a dialog box with a list of all the functions listed in the definitions file. When you select a function, VEE automatically configures the Call object with the correct input and output terminals and function name.

You can also configure the Call object manually by modifying the function name and adding the appropriate input and output terminals:

1 Configure the same number of input terminals as there are parameters passed to the function. The top input terminal is the first parameter passed to the function. The next terminal down from the top is the second parameter, etc.

2 Configure the output terminals so the parameters passed by reference appear as output terminals on the Call object. Parameters passed by value cannot be assigned as output terminals. The top output terminal is the value returned by the function. The next terminal down is the first parameter passed by reference, etc.

3 Enter the correct DLL function name in the Function Name field.

For example, for a DLL function defined as

   long foo(double *x, double y, long *z);

you need three input terminals for x, y, and z and three output terminals, one for the return value and two for x and z. The Function Name field would contain foo. If the number of input and output terminals does not exactly match the number of parameters in the function, VEE generates an error.

If the DLL library has already been loaded and you enter the function name in the Function Name field, you can also use the Configure Pinout selection on the Call object menu to configure the terminals.

The Delete Library Object

If you have very large programs you may want to delete libraries after you use them. The Delete Library object deletes libraries from memory just as the Delete Lib selection on the Import Library object menu does.

See Also

Overview of Compiled Functions, The Definition File, Using a Compiled Function, Importing and Calling a Compiled Function, Building a C Function, Using Dynamic Link Libraries


Using Dynamic Link Libraries

Use Dynamic Link Libraries

On PCs, you can use the compiled functions from Dynamic Link Libraries (DLLs) as a part of a VEE program. DLLs may be compiled functions that you have written yourself (contact Microsoft for documentation about writing DLLs), or DLLs that you have purchased or downloaded from the Web.

note

VEE supports both the "_cdecl" and "_stdcall" calling conventions. Most customer-written DLLs use the _cdec1 calling convention. Most Win32 API calls use _stdcall. VEE supports both naming conventions, so you can use most off-the-shelf DLLs as well as your own

Integrating a DLL into an Agilent VEE Program

This section describes how to import a DLL into a VEE program. Write or obtain the DLL as described above, then follow these steps to use the DLL:

1 Select Device [image] Import Library.

The Library Type includes three choices: UserFunction, Compiled Function, and Remote Function. Change the Library Type field to Compiled Function (the default is UserFunction). For a Compiled Function, the Import Library object includes a field for the Definition File as follows.

The fields are described as follows:

Field | Description
Library Name | The name VEE uses to identify the library. Generally, this is used if you want to delete the library after it has been used in the program.
File Name | File that holds the shared library.
Definition File | The include file with the prototypes of the functions. This is usually a *.h file.

note

You can also load a library manually during the development phase by selecting Load Lib from the object menu.

2 Select Device [image] Call.

When you have imported the library with Import Library, create a Call object by selecting Device [image] Call. You can then call the Compiled Function by choosing Select Function from the Call object menu, and choosing the desired function from the list box presented. For example, the Call object shown below calls the Compiled Function in myLibrary named myFunction with the parameters arraySize and array.

VEE automatically configures the Call object with the function name, and the proper number of input and output pins. The second, third... output pins map to any parameters passed by reference to the function. If you have entered the function name, you can also configure the object by selecting Configure Pinout in the object menu.

note

You can also call a DLL function from an expression field, provided the library has been loaded. When used in this way, you must enclose the parameters in parentheses after the function name, and the function only sends back its return value. Any parameters passed by reference can only be retrieved by using the Call object. For example, you might use the following expression in a Formula object:

2 * yourFunc(a,b)

The a and the b would refer to two input pins on the Formula object, and the return value of yourFunc would be multiplied by 2 and placed on the output pin.

3 (Optional) Click Device [image] Delete Library.

While developing the program, you can also select Delete Lib from the object menu to delete the library programmatically. Deleting the library after it has been used in the program reduces load time and conserves memory.

An Example Using a DLL

In this exercise, you will import a DLL and call a function from the DLL. The DLL used is included with the VEE product on Windows. (The same program is designed to work on all platforms.)

Open the manual49.vee file. It is located under:

<installation directory>\EXAMPLES\MANUAL\MANUAL49.

Examine this example closely.

Elements of above program.

Element | Description
Import Library | Before the first call to the compiled function Call Function, the DLL must be loaded using the Import Library object (in the Device menu).
Call Function | MANUAL49 calls a compiled function called myFunc. MyFunc requires a C datatype called long, which is the same as a VEE Int32. This number specifies the size of an array. The second input parameter is a pointer to an array of reals. The definition file is located in MANUAL49.H, and the source file for the C code is located in MANUAL49.C. MyFunc adds 1 to every element of the array.
Function Generator | The Function Generator is used to create a waveform, which is output to the array pin on the Call myFunc object.
totSize | The totsize object (in the Math & Functions box) is used to determine the size of the waveform, which is output to the arraySize input pin on Call myFunc.
XY Trace | The XY Trace object displays both the original and the new waveforms
Formula | The Call object output pin labeled Ret Value holds the size of the returned array, so that expression B[0:A-1] in the Formula object correctly specifies this array to the display object.

Run the program and notice that the second trace is one greater than the first trace at all points on the waveform.

Another key point to notice in the program is the method used for making it portable to all VEE platforms. Windows 98, Windows 2000, Windows NT 4.0, Windows XP, and Windows Vista (32-bit), use a Microsoft 32-bit compiler. These DLLs are all indicated using a *.dll extension.

The UserObject called Shared Library Name identifies the operating system being used, and then transmits the correct library name to the Import Library object as follows.

The whichos() function has been used in a renamed Formula object to identify the operating system. An expanded If/Then/Else object examines the output of the whichos() function, then triggers the appropriate text constant. This filename extension is then added to the MANUAL49 file using a renamed Formula object. (The input terminal on the Formula object labeled shared library has also been changed to ext.)

A control pin for a File Name has been added to the Import Library object; hence, there is a dotted line between the UserObject and the Import Library.

note

Investigate To/From Socket for sharing data in mixed environments, such as sending data to a database. Also, the example games Battleship and Euchre make extensive use of sockets to communicate between multiple VEE processes.

Using DLL Functions in Formula Objects

You can also use DLL functions in formula objects. With formula objects, only the return value is used in the formula. The parameters passed by reference cannot be accessed. For example, the DLL function defined above is a formula:

   4.5 + foo(a, b, c) * 10

where a is the top input terminal on the formula object, b is next, and c is last. The call to foo must have the correct number of parameters or VEE generates an error.

See Also

Overview of Compiled Functions, The Definition File, Using a Compiled Function, Importing and Calling a Compiled Function, Building a C Function, Creating a Dynamic Link Library


Importing and Calling a Compiled Function

To Import and Call a Compiled Function

You can import a DLL into your VEE program with the Import Library object, then call the Compiled Function with the Call object. The process is very much like importing a library of UserFunctions and calling the functions.

To import a Compiled Function library, select Compiled Function in the Library Type field.

Just as for a UserFunction, the Library Name field attaches a name to identify the library within the program, and the File Name field specifies the file from which to import the library. For a Compiled Function, there is a fourth field, which specifies the name of the Definition File as follows.

The definition file defines the type of data passed between the external routine and VEE. It contains prototypes for the functions.

After importing the library with Import Library, you can call the Compiled Function by specifying the function name in the Call object. For example, the Call object calls the Compiled Function named myFunction.

Select the desired function using Select Function from the Call object menu or from the Function & Object Browser (under Device [image] Function & Object Browser), or type the name in the Call object.

If VEE recognizes the function, the input and output terminals of the Call object are configured automatically for the function. (The necessary information is supplied by the definition file.) You can reconfigure the Call input and output terminals by selecting Configure Pinout in the object menu.

VEE configures the Call object with the input terminals required by the function and with a Ret Value output terminal for the return value of the function. There also will be an output terminal corresponding to each input that is passed by reference.

You can also call the Compiled Function by name from an expression in a Formula object or from other expressions evaluated at run time. For example, you could call a Compiled Function by including its name in an expression in a Sequencer or ToFile transaction.

However, only the Compiled Function's return value (Ret Value in the Call object) can be obtained from within an expression. If you want to obtain other parameters from the function, you have to use the Call object.

See Also

Overview of Compiled Functions, The Definition File, Using a Compiled Function, Building a C Function, Creating a Dynamic Link Library, Using Dynamic Link Libraries


Finding Functions in Large Programs

VEE provides a Find feature located in the Edit menu to help you locate objects and text in a large program. For example, open the Solitaire.vee program in the Examples\Games directory. Go to the detail view and click Edit [image] Find... to display the dialog box.

Type makeamove (a UserFunction in the Solitaire.vee program), as shown in the figure, and click Find. VEE automatically locates the UserFunction named makeamove and shows the part of the program from which it was called,

You can use Find to locate any object or text such as variables, titles, settings on objects, etc. Double-click on any line in the Find Results box to locate an object.

note

Find can also be used by placing the mouse pointer over objects in the Program Explorer and clicking the right button. This will limit the scope of the search to the particular UserFunction or UserObject.

See Also

Defining an Agilent VEE Function


What are Panels?

Panel Views (also called panels) are the user interface to your program. You generally create them after you've completed the functional part of your program. The Detail View (your development area) and the Panel View are two views of the same program that appear in the Main Window; just like heads and tails are the two sides of the same coin. You generally copy only display and data input objects to the panel. Only the objects themselves (and not the lines or pins) are displayed. You can then run your program in either view.

After creating a Panel View for your program, the program can also run in a separate execution window in the VEE work space. The execution window runs your program using all of the settings you specify for the Panel View. You can control the execution window’s use with the Main Window’s property Show On Execute. The execution window lets you observe both your program details and the Panel View at the same time, and shows what your finished program will look like when run in VEE RunTime. Only a small subset of menu items are available when the execution window is open to prevent program modification. However, securing your program and running it in VEE RunTime is usually the best way to deliver a finished program to your users. The following three figures show a paused program in its Detail View, the corresponding Panel View, and execution window.

A Detail View

The Corresponding Panel View

The Execution Window

VEE has three types of panels; they all are similar in the way you create, modify, and use them:

Main Panel - The panel associated with the Main context. If an object is in the Main work area, you can select and add it to the Main Panel. Building a Main Panel is described in To Add Objects to a Panel and To Delete Objects from a Panel.

UserObject Panel - Each UserObject can have its own panel. This panel can be used on its own or added to other panels, including the Main Panel. This panel can be visible all the time or popped up (like a dialog box) when the UserObject executes, and the Show Panel on Execute property is checked. Building a UserObject Panel is described in To Build a UserObject Panel.

UserFunction Panel - Each UserFunction can have its own panel (just like a UserObject). This panel pops up when the UserFunction executes, and the Show Panel on Execute property is checked, or when specified via a showPanel() function call. Building a UserFunction Panel is described in To Build a UserFunction Panel.


To Add Objects to a Panel

The Main Panel is the foundation of your user interface. No matter what type of panel you build, you use the same skills you do when building the Main Panel.

1. Put the object in its open view. Most of the time you want the open view on your panel; once the object is on the panel, you can't minimize or open it.

2. Select the object(s) you want added to the panel. You can select objects by pressing CTRL while clicking with the left mouse button on each object, or holding the mouse button down while dragging a selection box to include multiple objects.

3. Click the Add to Panel button on the toolbar ( or use Edit [image] Add To Panel).

Add to Panel button

You will now see the Panel View of your program in the Main Window. Switch between the Panel View and the Detail View by pressing the Panel and Detail buttons on the left side of the Main Window’s title bar. Any time you want to add other objects to the panel, start from the Detail View and follow the steps above.

Note

Objects selected from the Detail View are put in relatively the same position when added to the panel, and are moved to fit on the Panel View. You may need to reposition Panel View objects if you resize the window.

See Also

Lab 11-1: Using Menus

Lab 11-3: Creating a High Impact Warning


To Delete Objects from a Panel

1. Make sure you're in the Panel View.

2. Delete the objects. Select Delete from the object menu of the object

The object remains in the Detail View, but is deleted from the Panel View.

If you delete (Cut) an object from the Detail View, it is automatically deleted from the Panel View.

Note

If you Cut and then Paste objects on the Detail View, any associated Panel View objects are deleted and you'll have to add them to the panel again. Use Copy and Paste instead.

Note

When running a program, certain object menu actions, such as Delete, are not allowed in the Detail and Panel Views, and in the execution window. You must pause or stop the program first.


Changing the Appearance of a Panel

Generally, an object's appearance on the Panel View is unlinked from its appearance on the Detail View. For example, if you change the color of an object on the Panel View, it does not change the color of the associated object on the Detail View (and vice-versa). However, the data displayed and other execution-related information are linked; if changed in one view, it changes in the other. Changes in the Panel View appear in the execution window the next time you run the program.

When an object on the Panel View or the Detail View inherits the default properties that are set in Default Preferences (that is, you haven't changed the object’s colors or fonts properties), the properties will change when the system defaults change. These values are still not linked between Panel and Detail. For instance, an object on Panel can have its color set to gold while its color on Detail remains the default and vice versa.

Properties That Are Not Linked Between Panel and Detail Views

Show Title Bar (if object is shown in the open view)

Layout group properties:

Horizontal

Vertical

Show Digital Display

Show Tic Marks

Rectangular

Circular

Show Digital Display

Show 3-D Border

Scaled

Show Caption

Show Traces Legend

Show Scales Legend

Show Scale Labels

Show Scroll Bars

Show Auto Scale Button

Enable Trace/Scale Editing

Grid Type

Markers

Color Properties: all colors

Font properties: all fonts

Traces: all properties except trace name

Scales: all properties

Label Justification properties

Editing Enabled property (on Note Pad objects)

Format properties:

Radio Buttons | Cyclic Button | List | Drop-Down List | Pop-Up List | Slider List

Button | Check Box | Vertical Paddle | Horizontal Paddle | Vertical Rocker | Horizontal Rocker | Vertical Slide | Horizontal Slide

Limits category properties:

High Color

Mid Color

Low Color

Sub-Range Configuration category properties:

Colors

Icon appearance category tab properties:

Picture file and display mode

Show Title

Layout category properties (available on the Panel View only):

Size & Position (X, Y, Width, Height)

Border

All other properties are linked between Panel and Detail Views (a change in one view changes both views).


To Change an Object's Border Appearance

In the Panel View, you can change the depth appearance of an object by specifying a border option.

1. From the object menu, select Properties.

2. Go to the Appearance category.

3. Choose from the Border options: None, Flat, Sunken, or Raised.

The following figure shows the appearance of the different border styles.

Border Styles

Note: When The Border Is Set to None

When an object’s border is set to None, and the color matches the background color, the object's color extends to where the border would be. You can see where the border is when moving or sizing an object, or if you change the object’s color.

Regardless of the border setting, the object's size does not change. For example, if you've sized an OK object without a border, and then choose to have a border, part of the object text may be obscured by the border. In the following figure, both objects are the same size. The one on the left has Border set to None; the one on the right has Border set to Flat.

A Border Width Example


To Label Areas

To add text to an area on the panel, use the Label object.

1. From the Detail View, select Display [image] Label.

2. From the Label object's object menu, select Properties.

3. Change the title to the desired label text.

4. Select the Label object and select Edit [image] Add To Panel. Position the label where you want it.

The Label object color by default is tied to the default Panel View color (set from File [image] Default Preferences) so that the label background blends invisibly into the Panel View.

You change the label text from either the Detail or Panel View by changing the title text via the Properties window, or programmatically change the label text at run time by adding a data input terminal. You can also change the justification of text by specifying Left, Right, or Center justification via the Properties window.


To Align Objects

When you add an object to the Panel View, its upper-left corner is automatically aligned to a user-definable grid, but the size of the object is not changed. When you move an object on the Panel View, its upper-left corner aligns to the nearest grid detent. To resize the object to the grid, move the cursor to the lower-right corner of the object, get the corner resize cursor, and click. If the corner resize cursor is difficult to use, then use Size on the object menu.

There are several ways to align objects:

1. Select the objects and use Edit [image] Align or Distribute.

2. Select the objects and, in the Properties window, you can set the size of all the objects.


To Change the Grid Size

1. From the Main Window’s object menu, select Properties.

2. Select the Panel category.

3. Set the PanelGridSize. The smallest grid size is 2.

4. Change PaneDrawGrid to True to see the grid.

When you change grid size, existing objects on the panel do not automatically align to the grid. When you click on an object, its upper-left corner aligns to the nearest grid detent. When you click on the corner resize area, the object resizes to the nearest grid detent. Any Move or Size aligns the object to the current grid size.

You can move or size an object off-grid by holding the Shift key while clicking to move or size the object.

Note

Each panel has its own grid. To change the grid size on a UserObject or UserFunction grid, select Properties from its object menu and then follow the rest of the steps listed above.


To Match Object Sizes

You may want to match the size of one object to the size of another object in the Panel View.

There are several ways to do this:

1. Turn on View [image] Properties. Select all of the objects. In the Properties window, under the Layout category, set the values for size.

2. Select all of the objects. Move the mouse to the bottom right of one object until the size cursor (double-headed arrow) appears. Hold down the CTRL key while pressing the left mouse button down. Drag all the objects sizes to the desired size. Use Undo if the size is not what you wanted.

See Also

To Change Properties Programmatically


To Add a Picture to the Panel

There are two ways to add a graphical image, such as a bitmap, to a Panel View. These methods refer to the Main Window, and can be used with UserObjects, and UserFunctions, too.

To add an image directly to the background of the Panel View

The Panel View must already exist to use this method. A quick way to create a blank Panel View is to click Create Panel on the Main Window’s object menu.

1. From the Main Window’s object menu, select Properties.

2. Go to the Panel category. This tab appears after a Panel View has been created.

3. Choose Panel BackgroundPicture, select file.

4. Select a display mode: Actual, Centered, Scaled, or Tiled. See Picture Display Modes below.

5. Click OK.

To place one or more movable and sizable images on the Panel View

1. From the Detail View, select Display [image] Picture. The Picture object appears in the Main work area.

2. From the object menu of the Picture, select Properties.

3. Choose a Picture file.

4. Select a display mode: Actual, Centered, Scaled, or Tiled. See Picture Display Modes below.

5. Click OK.

6. Select the Picture object.

7. Select Edit [image] Add To Panel.

Tip

You can programmatically change the image on a Panel View by adding a data input terminal to the Picture object.

The currently supported graphics formats are:

Bitmap (*.BMP)

GIF87a (*.GIF)

Windows MetaFile (*.WMF)

Portable Network Graphics (*.PNG)

Picture Display Modes

Actual - The picture is displayed in its actual size. The object or panel is resized to the size of the picture.

Centered - The picture is displayed in its actual size. The picture is centered on the object or panel (which remains the same size).

Scaled - The picture scales to the current size of the object or panel. After this choice is selected, the scaling may take a few moments.

Tiled - The picture remains at its actual size, but is repeated horizontally and vertically until it fills the entire object or panel.

The following picture shows the different display modes.

A Picture Object With Different Display Modes

Note

To increase execution speed, VEE caches graphic images. If you've loaded an image into VEE and then changed the file that contains your image, you need to select a different image file, and then re-select the original image file. Once you've done that, the new image is used.

See Also: Lab 11-2: Importing Bitmaps for Panel Backgrounds


What is a UserObject Panel?

A UserObject Panel is very similar to the Main Window’s Panel. Each has its own context, so each has its own Trig Mode and Edit menu, as well as its own Panel View. A UserObject Panel is more flexible than the Main Panel in the ways it can be displayed.

There are three ways to display UserObject Panels

Independent Panel: A Panel on a UserObject.

This method is useful when you want to bundle your UserObject for someone else to use or to simplify parts of your program for someone else to use without building a Main Panel.

Pop-Up Panel: A panel on a UserObject with Show Panel on Execute specified.

This method is usually used for custom dialog boxes that query for information, and then go away. This type of panel pops up anywhere in a VEE window.

A Panel on the Main Panel: A panel on a UserObject that is then added to the Main Panel.

This method is used to group functionality. You can also nest panels on other panels.

The following figure shows the different types of UserObject Panels.

Three Ways to Display a UserObject Panel


To Build a UserObject Panel

1. In the UserObject’s edit window, select the object(s) by pressing Ctrl, then clicking with the left mouse button on the object(s).

Note

Objects to be put on the UserObject Panel must be in the UserObject's Detail View. You cannot select objects from outside the UserObject boundaries or from nested UserObjects.

2. From the UserObject's Edit menu, select Add To Panel.

Now you've created a UserObject Panel View that is independent of the Main Panel. You switch between the Panel View and the Detail View by pressing the Panel and Detail buttons on the left side of the edit window's title bar. Any time you want to add other objects to the UserObject panel, start from the Detail View and follow the steps above.


To Build a Pop-Up Panel

Once you've created a UserObject Panel, follow these steps to make the panel pop up when the UserObject executes:

1. From the UserObject's object menu, select Properties.

2. In the Pop-Up Panel category, set ShowPanelOnExecute to True.

3. Click OK.

While the program runs and the UserObject executes, the UserObject Panel pops up and is visible on both the Main Window’s Detail View and Panel View (if it exists). If the Main Window property ShowPanelOnExecute is turned on, the UserObject Panel pops up only in the Execution Window.

Note

To change the appearance of the Pop-Up Panel, set the ShowPopUpPanelTitle and ShowPopUpPanel Border properties in the Pop-Up Panel category in the Properties window.

To change the background color of the Panel View, set the BackColor property in the Appearance category of the Properties Window.

Note

You generally use a Pop-Up Panel when creating a custom dialog box. For details, refer to Building a Custom Dialog Box.

If you need a simple dialog box, you may not need to create a Pop-Up Panel. Use one of the Dialog Box objects. For details, refer to About Built-In Dialog Box Objects.


To Keep a Pop-Up Panel Displayed

Once you've created a Pop-Up Panel and run it, you may notice that it flashes up and is instantly gone. This action happens because nothing pauses the execution of the UserObject, therefore you can't see or respond to the information on the Pop-Up Panel. Follow these steps to add an OK button to maintain execution of the UserObject until you click on the button.

1. Select Flow [image] Confirm (OK).

2. Place the OK object on the Detail View of the UserObject.

3. Select the OK object.

4. From the UserObject's Edit menu, select Add To Panel.

Now when you run the program, the UserObject Panel pops up and stays up until you press the OK button.

For details about using OK and Cancel buttons and creating custom dialog boxes, refer to Building a Custom Dialog Box.


To Change the Size of a Pop-Up Panel

The size of a Pop-Up Panel is the size of the Panel View of the UserObject. Follow these steps to change the size.

1. Put the UserObject’s edit window in its Panel View by pressing the Panel button on the left side of the UserObject's title bar.

2. Resize the panel to the desired size.

From the object menu, select Size. Or position your cursor at an edge of the object and resize by dragging the edge.

When you resize the UserObject Panel, you're including the size of the title and border.


To Change the Location of a Pop-Up Panel

The first time you run your program, a Pop-Up Panel is displayed in the center of the VEE work area. You change the location of a Pop-Up Panel by repositioning the panel while the program is running.

1. Press Run.

2. When the panel pops up, drag it to the desired location.

Every time the program is run, the panel will pop up to that location. Note that you can position the Pop-Up Panel to any location, the grid does not affect the location. If the Main Panel property Show on Execute is turned off, you can reposition the UserObject Pop-Up Panel anywhere in the VEE work space. If Show on Execute is turned on, the Pop-Up Panel can be repositioned only within the Execution Window border.

Note

The location of the upper-left corner of the entire Pop-Up Panel stays in the same place regardless of the Pop-Up Panel properties, or whether Show Title Bar and Show Border are selected or not. For example, if you have set the location of a Pop-Up Panel and then turn off Show Title Bar, the panel will shift so that the upper-left corner of the Pop-Up Panel is now located where the upper-left corner of the Pop-Up Panel's title bar was.


To Add a UserObject Panel to the Main Panel

Once you've created a Panel View in a UserObject edit window, follow these steps to add this panel to the Main Panel.

1. In the Main Window’s Detail View, click on the UserObject icon using the right mouse button, then select Restore.

The UserObject icon expands into the Panel View that you created in the UserObject’s edit window.

2. Select the UserObject.

3. Select Edit [image] Add To Panel from the main menu.

Now you'll see the Main Window’s Panel View with the UserObject Panel displayed on it.

You can nest a UserObject Panel on its parent UserObject Panel by following the same steps above, except you must use the Edit menu of the parent UserObject.

Once the UserObject Panel has been added to the Main Panel, change its size, location, and other appearance details the same way you change them for objects on any other panel as described in Changing the Appearance of a Panel and related topics.

Note

When you nest a panel on another panel (as described above), you're making a copy of its contents, and the copy is linked to the original. However, the copy is locked; to change the panel, you must make the changes to the original UserObject Panel. When add or delete objects from the nested panel, or otherwise change the original UserObject Panel, the copy is also changed.


To Add Objects to a Nested UserObject Panel

Once a UserObject Panel has been added to the Main Panel (or to a parent UserObject Panel), you can still add objects to this panel. However, you must add these objects to the original UserObject Panel, then adjust sizes and positions of related objects and panels.

1. Return to the Main Window’s Detail View by pressing the Detail button on the left side of the Main Window title bar.

2. Access the UserObject’s edit window.

If the UserObject is in its icon view, double-click it.

If the UserObject is in its restored view, select Edit UserObject from the object menu.

3. Put the UserObject’s edit window in its Detail View by pressing the Detail button on the left side of the title bar.

4. Add any desired objects to the UserObject’s Detail View.

5. Select the new objects to add to the panel. From the UserObject's Edit menu (click the mouse’s right button), select Add To Panel.

6. Rearrange objects on the UserObject Panel View for a good appearance. You may need to resize the panel.

7. In the Main Window, click on the Panel View button to view the UserObject panel with the new objects. You may need to resize the panel so all objects are visible.


To Delete Objects from a Nested UserObject Panel

1. Return to the Main Window’s Detail View by pressing the Detail button on the left side of the Main Window title bar.

2. Access the UserObject’s edit window.

If the UserObject is in its icon view, double-click it.

If the UserObject is in its restored view, select Edit UserObject from the object menu.

3. Put the UserObject edit window in its Panel View by pressing the Panel button on the left side of its title bar.

4. Delete the objects you want removed from the nested UserObject panel by selecting Delete from their object menus.

The objects still exist in the UserObject’s Detail View. If you want to remove them from the program, delete the objects from the Detail View instead, which also deletes them from the Panel View.

5. Rearrange objects on the UserObject Panel View for a good appearance. You may need to resize the panel.

6. In the Main Window, click on the Panel View button to view the edited UserObject panel. You may need to resize the panel.


To Delete a UserObject Panel from the Main Panel

1. In the Main Window, go to the Panel View by pressing the Panel button on the left of the title bar.

2. Delete the UserObject Panel. From the object menu select Delete or double-click on the object menu button.

The UserObject Panel still exists, but it is no longer added to the Main Window’s Panel View.


What is a UserFunction Panel?

A UserFunction Panel is built and runs basically the same way as a UserObject Panel. However a UserFunction Panel is only visible when the UserFunction is executing (a Pop-Up Panel) or if programmatically displayed via showPanel(). A UserFunction Panel cannot be added to the Main Panel (or parent UserFunction or UserObject Panels).


To Build a UserFunction Panel

If you have a UserFunction and want to create a panel for it, follow these steps.

1. Select the object(s) in the UserFunction’s Edit Window by pressing CTRL, then clicking the left mouse button on the objects you want.

Note

Objects on the UserFunction Panel must be in the UserFunction's Detail View. You cannot select objects from outside the UserFunction boundaries. UserObject Panels nested inside a UserFunction can be added to the UserFunction Panel. For the method to do this, see To Add a UserObject Panel to the Main Panel .

2. From the UserFunction's Edit menu, select Add To Panel.

Now you've created a UserFunction Panel View. Switch between the Panel View and the Detail View by clicking on the buttons at the left end of the UserFunction title bar.

3. Close the UserFunction Edit Window when you are finished editing.

Any time you want to add other objects to the panel, start from the UserFunction's Detail View and follow the previous steps.

Note

If you have already created a UserObject Panel and then made the UserObject into a UserFunction, the UserFunction Panel automatically exists. If the UserObject Panel was added to the Main Panel, it was automatically deleted because a UserFunction Panel cannot be on the Main Panel.


To Build a UserFunction Pop-Up Panel

1. Select Edit [image] Edit UserFunction.

2. Select the UserFunction name.

3. From the UserFunction's object menu, select Properties.

4. In the Pop-Up Panel category, change the ShowPanelOnExecute check box to True.

The UserFunction Pop-Up Panel operates the same way as a UserObject Pop-Up Panel as explained in To Build a Pop-Up Panel.

Note: To Build a Status Panel

A status panel is programmatically popped up with showPanel(). For details refer to Building a Status Panel.


To Change the Size of a UserFunction Pop-Up Panel

1. Select Edit [image] Edit UserFunction.

2. Select the UserFunction name.

3. Switch the UserFunction to its Panel View.

4. Resize the panel to the desired size.

From the object menu, select Size. Or position your cursor on an edge of the object and resize by dragging the edge.

When you resize the UserFunction Panel, you're resizing the entire UserFunction area including the title, and the border.


To Change the Location of a UserFunction Pop-Up Panel

Follow the same steps as with a UserObject Panel shown in To Change the Location of a Pop-Up Panel.


Making Your Panel Keyboard Navigable

Perhaps your users prefer to navigate around the Panel View using only the keyboard or perhaps they do not have access to a mouse in their environment. For these users, build a panel that is keyboard navigable.

In general, when using the keyboard to run a program, first an object must get focus, then the object's data value or state can be changed.

Definition

Focus is a term indicating a location where you can perform an action. In VEE, the object or field that has focus is either surrounded by a marquee (a dotted rectangle) or, for a type-in field, a vertical caret is shown and existing text is shown in inverted colors (text is selected) if the object was tabbed to; if an object was clicked-on, it gets focus but the appearance of the existing text is not changed.

There are several things to remember about keyboard navigation:

It's hard for the user to tell when the object on the Panel View has operated (except OK buttons which are grayed out unless they can be selected). Inform the user that an object has operated or have the user indicate when they have finished making changes (for example, by pressing an OK button).

Without a mouse, the user can't access an object's object menu (this access is useful with Display object menu choices such as Zoom and Auto Scale). You can add control input terminals for some of these parameters, if you need to let your user use them.

You can specify the tab order of tabbing through a Panel View. The pattern is discussed in Panel View Navigation Techniques.

Different objects have different rules for keyboard interaction. You must tell the user what they are; see Panel View Selection Techniques for details.


To Give Focus to an Object or Panel

Some information about focus

You can set the tab order of the objects on each panel. On each object, set the Properties for TabIndex and TabStop.

You can modify the data on an object only when it has focus.

When a panel pops up, only objects on the Pop-Up Panel get focus until the panel is closed.

Only objects with data fields, buttons, or a selection area can get focus. Note that every data field, button, or selection area can be tabbed into.

For example, if you have a Slider on the panel (as shown in the following figure); the first Tab gives focus to the MinValue field.

A Slider on a Panel

To prevent users from tabbing through these fields and changing them, add control input terminals for fields such as MinValue and MaxValue.

Selection Control, Toggle Control, and Slider objects execute as soon as the program starts to run unless the Wait for Input property has been set. This property allows these objects to execute only after they get focus and have values changed or selected.

If Esc or Enter is assigned to an OK button and then pressed, the OK button gets and keeps the focus.

If a function key is assigned to an OK button and then pressed, the focus stays on the object that had focus before the function key was pressed.

Note

Do not use VEE's built-in Dialog Box objects on a keyboard-driven panel that contains other objects. After the Dialog Box object stops executing, no other object gets focus, so you can't navigate to other objects via the keyboard. For information about Dialog Box objects, refer to About Built-In Dialog Box Objects.


To Assign an OK Button to the Enter or Esc Key

When you create a panel, you can assign a Confirm (OK) button to the Enter and Esc keys on the keyboard. This lets anyone using your program press a specific keyboard key rather than the Confirm (OK) button. Otherwise, the user must Tab to the button and press Space. This feature is especially useful on custom dialog boxes made from Pop-Up Panels. For more information about building custom dialog boxes refer to Building a Custom Dialog Box.

To assign these keyboard keys to Confirm (OK), follow these steps:

1. Select Flow [image] Confirm (OK).

2. Add the Confirm (OK) button to the panel.

3. From the OK button's object menu, select Properties.

4. Select Assign to [Enter] Key and/or Assign to [Esc] Key to True.

Note
You can assign the Enter key to only one OK button per context and you can assign the Esc key to only one OK button per context. If you assign either of these keys to more then one OK button per context, the previous assignment is automatically turned off.

5. Changes take effect immediately.

When the program runs, any OK button assigned to Enter has its label appear in a bold font to indicate that it is the default button.

Note
The Enter and Esc keys can only have a Confirm (OK) button assigned to them from the Panel View of your program (or UserObject/UserFunction). To assign Confirm (OK) to other keys, see To Assign a Button to a Function Key.


To Assign a Button to a Function Key

When you create a panel, you can assign a Confirm (OK) button to a function key (F1, F2, F3, etc. at the top of the keyboard). This lets anyone using your program press a specific keyboard key that is equivalent to the Confirm (OK) button. Otherwise, the user would have to Tab to the button and press Space. To assign keyboard function keys to Confirm (OK), follow these steps:

1. Select Flow [image] Confirm (OK).

2. Add the Confirm (OK) button to the panel.

3. From the OK button's object menu, select Properties.

4. Select the Assign to Function Key dropdown.

5. Select the function key to assign to this OK button (F1 through F12). Some keyboards have only eight function keys, but VEE allows you to select any of the choices to allow cross-platform development; see General Tips for more information. In Windows, the F10 key is a reserved key that functions the same as Alt.

Note
You can assign a specific function key to multiple OK buttons. When the function key is pressed, all of the associated buttons that are currently active will operate.

The title of the OK button is automatically changed to reflect the function key assignment. You can change the title to exclude the function key information.

Note
You can use function keys to press an OK button from either the Panel View or the Detail View. Key assignments also work in the execution window when the ShowPanelonExecute property is turned on for the Main Window.


Panel View Navigation Techniques

To navigate around a Panel View, use the Tab key to go forward and Shift+Tab to go back.

For Earlier Versions

Beginning in VEE version 8.0, you can configure the tab order of objects on panels programmatically (at run time) without affecting their design-time values. For more information on changing tab order programmatically, see To Change Properties Programmatically

Beginning in VEE version 7.0, you can configure the tab order of objects on panels. Via the Properties window, you can set the TabIndex and TabStop values for each object on a panel. You can do this for new programs, and for pre-7.0 programs that have been imported into 7.0.

Note: Pre-7.0 programs loaded into VEE 7.0 and later, are, by default, set to the TabIndex property of each object on a panel according to the algorithm in the section below “Tab Order in Programs created in VEE 6.2 and earlier”. Thus, old programs will execute in 7.0 with the same behavior as in prior versions of VEE.

Programs loaded into 7.0 may be modified to explicitly set the TabIndex value for objects on each panel. The object with property TabIndex set to value zero (0) is the first object that is tabbed to when that panel pops up. Note: multiple objects on the same panel can have the same TabIndex value (z-order of these objects then determines tab order). This behavior is not recommended but is allowed.

TabStop is used to remove an object from the tabbing order. Some objects, which do not allow any operator input, such as an AlphaNumeric display, have their TabStop value set to false. Other objects can have this property set to false if the desired behavior is to have the object appear on a panel but not allow the operator to tab to that object.

When editing a program in VEE 7.0 and later, new objects added to panel will by default have their TabStop property set to one higher than the existing highest TabStop value on that panel. For example, if you have a panel with three objects with their TabStops set to 0, 1 and 2, and you add another object to that panel, the new object by default will have its TabStop property set to 3.

When a panel is executed, the object with TabIndex zero (or the lowest value) is given initial focus. Tabbing will then proceed to the object with the next TabIndex value, progressing from zero to the maximum TabIndex value.

For older versions (6.2 and prior), the order in which the objects and panels are traversed is as follows:

After you press Run, VEE divides the panel into groups of objects. The first group is determined by the topmost (lowest y-coordinate value) object and contains all objects that have a y coordinate close to that of the topmost object. The first object to get focus is the leftmost object in the group. Tab moves the focus from left to right.

Note
If the leftmost object has Auto Execute set, it does not get the focus first, but you can Tab to the object.

The y-position of an object or panel is determined by the location of its upper-left corner.

Once the focus has gone as far right as it can in the first group, it continues with the leftmost object in the next group.

The next group is determined by the topmost object that was not in the previous group. Tab starts at the leftmost object in this group and continues to the right. This ordering repeats throughout the panel.

The following figure shows a typical grouping of objects.

A Simple Tabbing Order Example for Programs Created in VEE 6.2 and Earlier

The following figure shows a more complex grouping of objects. At first it appears that the Third Text object should be included in the first group. But the first group is determined by the Second Text object, therefore the Third Text object is too far down to fit into the first group.

The third group is determined by the Fifth Text object. The Fourth and Sixth objects are close enough to be in that group.

A Complex Tabbing Order Example

Note
An OK button can only be tabbed to when it is activated (when the text is not grayed out).

If an object has multiple fields, Tab takes you through all the fields before going to the next object.

If you are in a UserObject Panel nested on another panel, Tab takes you through all the objects in the UserObject before continuing to the next object out of the UserObject Panel.

If you are in a Pop-Up Panel (UserObject or UserFunction), you can Tab only within the Pop-Up Panel until it finishes executing.

Remember that you can Tab to objects whether or not they've executed (except OK objects).


Panel View Selection Techniques

When using a mouse, you click to select a choice or change a value. When using a keyboard, you tab to the object to give it focus and then you select a choice or change a value by using the following techniques:

Radio Buttons and List:

and [image] to select a choice.

Space to select the current choice.

Cyclic Button:

Space to change the choice.

Drop-Down List:

to get the list.

and [image] to select a choice.

Space or Return to put the list away.

Esc to cancel the choice.

Pop-Up List:

Space to get the list.

and [image] to select a choice.

Space or Return to put the list away.

Esc to cancel the choice.

All Toggle Control objects:

Space to change the value.

All Edit Fields (such as Constant objects):

Type in a new value.

Tab or Enter to continue to the next field.

Esc cancel the changes.

Start and OK Buttons:

Space to select them.

Objects with multiple fields (such as Function Generator):

Select a choice or change a value using one of the techniques listed above depending on the type of field, then Tab to the next field.

Note

If you have Esc or Enter assigned to an OK object and you use Esc or Enter in an edit field (such as in Constant and Slider objects), the OK button will be pressed after the edit field data is entered.

When a Data [image] object has Wait For Input set, it executes when you select a choice or change a value as described above. When a Data [image] object has Auto Execute set, it starts the thread running when you select a choice or change a value as described above. To see an example that demonstrates Wait for Input, refer to To Build a Self-Modifying Panel.

Note

Data in Data [image] Constant and Data [image] Slider objects must be changed for Wait For Input or Auto Execute to work. Replacing a character with the same character is interpreted as a change.


Most Important

The topics about developing good user interfaces contain guidelines and general interface design information. This information is not a substitute for Human Factors help or comments from users.

Get advice from a professional user-interface designer such as a Human Factors engineer or graphical designer. The information in this section contains only rough guidelines. If you have access to a user-interface designer, ask them to look at your Panel Views and give you comments.

Get user feedback. Let your users use the panel. Ask them if they can find the information needed. Make sure they can identify what they should do. Verify that the colors and fonts are useful and that they allow comfortable long-term use.

General User Interface Design Guidelines

Know your users and their environment.

Empower users. Let them control the basic characteristics of the program. Minimize the number of rules users must learn to use the system.

Be consistent in user interactions, data presentation, and layout. Group and order the information displayed.

Accommodate different levels of users via defaults, help, or templates for novice or intermittent users, and accelerators or shortcuts for advanced or frequent users.

Build users' confidence. Help them accomplish their tasks quickly and without frustration. Do not use accusative wording like user error.

Provide feedback to users. Let them confirm data input or directly see the result of their actions.

Orient users. Provide them with enough information to understand the current state of the program and how to respond to this state.

Design for error recovery. When users make mistakes, they need a chance to recover from them.

Verify your design with the real users of the program.


Using Colors

When using colors in your panels, consider the limitations of colors for your audience and the specific uses for color.

Facts about Colors

Older people are often less sensitive to color and may need brighter color levels. The ability to discern shades of blue may be diminished. However, younger users may find brighter colors more fatiguing.

Eight percent of men and 0.5 percent of women have some form of color deficiency. The most common deficiency is an inability to distinguish between red and green.

There are individual variations in color perception. Different monitors, different environmental lighting, cultural and occupational connotations, and personal preferences for colors can all affect the way people see, distinguish, and perceive color.

Be aware that colors have different meanings in different cultures; it's best to use neutral colors for large areas.

Note: Redundant Cues

Because of the reasons listed above, use color only as an additional form of communication. For example, to distinguish a Stop from a Go button, don't just change the color from Red to Green; also make sure there is explanatory text that changes. One way to make sure your color is used as a redundant cue is to first create the panel without specifying colors, and then add them as needed.

Use as few colors as possible. More than four or five different colors on a single panel or seven different colors in your entire user interface, may be distracting and confusing.

Colors project an image about your program. Bright colors may project a toy-like quality. Muted or subtle colors may create an impression of sophistication or professionalism.

For background and text (foreground) combinations, use colors that have high contrast; but avoid putting colors from opposite sides of the color wheel together (like yellow and blue). The contrast is good, but boundaries may bleed into one another. The following figure shows the colors on a color wheel.

A Color Wheel

Use generally-accepted color encodings, such as Green for Go or Normal Status and Red for Stop or Emergency. This color coding may be dependent on cultural or occupational standards.

Consider the printing needs of your audience. If the user prints a color screen to a color printer, the colors on the printer won't necessarily match those on the screen due to printer limitations. If the screen is printed to a non-color printer, make sure the colors translate well to black and white. Note that on the Default Preferences Properties dialog box, the Printing tab Screen Element settings do not apply to color changes from the default colors. When you've changed colors from the defaults, VEE automatically gray-scales the colors on the printout.

So if it's so troublesome, why use color?

To enhance the aesthetics. An interface with pleasant-looking colors is easier to operate and view for long periods of time.

To group objects together visually.

To aid navigation and recognition.

To enhance readability.

To show what is similar and what is different. Different colors distinguish different groups of information from each other.

To call attention to an object or event. It's easy to find information if it is colored differently.

To accentuate information encoding. Color information can aid understanding, especially when using common encodings like Yellow for caution, Red for danger or failed, Blue for water or cooling.

Use a basic overall color scheme, keeping similar functions the same color and only use contrasting colors when needed.


How to Pick Colors

Here are some guidelines to help you pick colors that enhance the usability and readability of your panel.

Generally you want to use a neutral-colored background, White or Gray is best. However, lighter colored backgrounds increase the perception of flicker (the amount depends on the system monitor). Shades of Blue are also very good for backgrounds (for both objects and panels).

If your background color is too light, the border highlight of a 3-D object may not stand out. If the background color is too dark, the object's border shadow may not stand out.

When displaying text, pick colors that have good contrast with the background. For example, if the background color is White, the following colors are the best and worst for text:

Black - Best

Blue - Best

Red - Best

Yellow - Worst (low contrast)

Cyan - Worst (low contrast)

If the background color is Black, the following colors are the best and worst for text:

Yellow - Best

White - Best

Green - Best

Blue - Worst

Red - Worst (may bleed into the background)

Magenta - Worst (may bleed into the background)

Note that on VEE display objects (such as X vs Y), the default background color for the graph is black, and you'll want to pick good colors for the graph’s grid lines. You can also change the trace line and point types to distinguish the graph traces.

The following figure shows how these colors can be used:

Displaying Different Color Text

This program is saved as colors.vee in your manual examples directory. Open this example to see what these colors look like on your screen.

Regardless of the background color, make sure that the color of the text displayed is about the same level of brightness and has good contrast. These guidelines for object background and text also apply to panel backgrounds and objects placed on them.

Generally, shades of Blue work best as a background. To use Blue as a text color, use a greenish blue (like Teal).


Using Fonts

Facts about Fonts

It takes users about 25% more time to read text on a computer screen than on paper. Comprehension is about the same. Therefore, putting large amounts of text on your panel will slow down your user.

There are proportional and non-proportional fonts. A proportional font uses different widths for different letters; for example, the space used to print the letter w is wider than the space used to print the letter i. Proportional fonts are generally easier to read and look better. Some common proportional fonts are: Lucida*, Arial*, and Time New Roman*.

A non-proportional font uses the same width for all letters and is used when you need to vertically align data in a table. Some common non-proportional fonts (also called mono-spaced fonts) are Courier and Courier New.

The fonts available in VEE depend on the fonts installed on your system.

Font size indicates the height of characters, not the width. So if you change the font type, but keep the font size the same, you may have to resize the object to accommodate the text width.

Generally, use a 12-point font size for text meant for general reading. You may want to use a larger font or a bold font for emphasis. Although font size on paper is an absolute size (like inches or centimeters), fonts on a computer screen are based on logical font size, which varies according to your monitor resolution. So no matter what size font you use, you'll need to make sure it is readable on the screen. The following figure shows different font sizes.

Font Sizes

Some studies show that serif fonts (those with thin lines at the top and/or bottom of the main strokes of the letter) allow the user to read faster than sans serif fonts. You'll need to see if this makes a difference for your users. The following figure shows a serif and a sans serif font.

Serif and Sans Serif Fonts

Text is faster to read if it is left-justified with a ragged right margin.

Use no more than three different font types, and four font colors per program. Use fonts consistently to help the user understand which text is more important. Generally, larger text is the most important.

Use font types and sizes consistently to make it easier for you to align and balance the text across the screen.

Blue is generally a bad color for text - the eye is least sensitive to this color.

Verify your font choices with the users of your program to ensure legibility.

* Arial and Times New Roman fonts are products of the Monotype Corporation.
Lucida font is a product of Bigelow & Holmes, Inc.


Layout Tips

Maintain a consistent layout even as the panel's content changes. For example, if you have a message area at the bottom of the screen, a display area on the side, and a status area at the top - stay with this layout; don't move elements around as the program runs.

Group related information.

Balance information through the available screen area.

Remember to leave white space (blank areas without objects) to make your panel easier to use. If the screen is full, with objects positioned against other objects with no space between them, it is harder for your user to find needed information.

Always place navigation controls in the same place on every panel.

Align and size objects in related groups so they are the same size. Align them horizontally or vertically so that there is not a ragged edge to disrupt identifying and scanning the objects. Make the spacing between objects a constant distance.

Use dialog boxes to present infrequent or low-use features. This lets the user respond and be done with this information, and reduces clutter on the Main Panel.


To Call Attention to an Object

Use visual attributes to call attention to areas on the screen:

Use object size. The eye is naturally drawn to larger objects. There also is a connotation of importance. If you are differentiating information by size, use a maximum of five different sizes.

Use border characteristics to distinguish objects. Use lighter colors on the raised surfaces and darker colors on the recessed surfaces. To see the different border styles, refer to the figure Border Styles.

Use different colors to indicate different levels of importance. You should use a maximum of four or five different colors on a panel. And a maximum of seven different colors in your entire user interface. If you decide to use more, supply a legend to explain each color's purpose or meaning.

For fine details or small areas, black, white, and gray give the best readability.

Brighter colors attract more attention than dimmer colors (for example, using Blue, Yellow, or Red, instead of Blue Gray, Gold, or Light Red). Users can differentiate between a maximum of five different brightness levels.

Lighter colors and warmer colors (such as Red) appear to advance to the user. Darker colors and cooler colors (such as Blue) appear to recede.

Use font size. Use at least four points of size difference to denote relative importance.

Use font styles such as bold and italics. Italics makes text slower to read, so don't use italics for text requiring quick reading.

Blinking/Flashing is an excellent way to get attention. With VEE, some ways to direct attention are to pop-up a panel, change bitmaps in a Picture object, change colors and text in a Color Alarm object, or use a Dialog Box object. No more than four items should be blinking or flashing at a time.

Another way to draw attention is to use sound. Use the Beep object (if the hardware supports it).

Each of these attributes should be used in a consistent way throughout your program.


About Built-In Dialog Box Objects

Before creating a custom dialog box, consider if the built-in Dialog Box objects (located under the Data menu) will meet your needs. They are easy to use and have many useful features.

The differences between Dialog Box objects and Pop-Up Panels (used to build custom dialog boxes) are:

Dialog Box objects do not need to be added to a panel, they pop up automatically. The following figure shows a Message Box object and the panel it generates.

A Message Box

Dialog Box objects perform only one operation per object - they ask for specific user input. If you need to ask the user several questions at once, or to display data, then create a custom dialog box.

Dialog Box objects are modal. In other words, while they are popped up, the rest of the program is stopped. This is different than Pop-Up Panels; while Pop-Up Panels are popped up, the rest of the program continues to execute.

Dialog Box objects should not be used on a keyboard-driven panel. After they finish executing, no other object gets focus, so you can't navigate to other objects via the keyboard.

Dialog Box objects already have many built-in features. You don't have to write a program to get features such as constraint checking or timeouts. The built-in features of the Dialog Box objects are listed in the following table:

Dialog Box Object Features

_________________________________________________________________________________________________

Dialog Box Object

Constraint Checking

Password Masking

Timeout

Custom Button Text

Formatting Options

_________________________________________________________________________________________________

Text Input Gets text input | X | X | X | X | X Field Width
Int32 Input Gets integer input | X | X | X | X | X Field Width
Real64 Input Gets real input | X | X | X | X | X Field Width
Message Box Displays information | n.a. | n.a. | X | X | X Multiple Line Messages
List Box Allows single or multiple selection from a list | n.a. | n.a. | X | X | X List Height
File Name Selection Allows file name selection | X[1] | n.a. | n.a. | n.a. | n.a.

_________________________________________________________________________________________________

1 Gives a warning if overwriting an existing file. Doesn't allow opening a non-existent file.

Dialog Box objects have additional color and font properties so you can easily control the appearance of the pop-up panel. The following figure shows these properties.

Message Box Properties on the Colors and Fonts

Dialog Box objects are easy to use without a mouse. You press the Enter key to press the default button; or press the Esc key to press the rightmost button (usually Cancel). Use Tab and Shift+Tab to move the focus to input fields or buttons. Press Space to press a button that has focus. Refer to Making Your Panel Keyboard Navigable for information about focus.

For more details refer to Dialog Box, and To Output a Value on Timeout.


To Output a Value on Timeout

When you set a Timeout on a Dialog Box object (via the Properties dialog box), and the timeout period expires, the value 1 is output on the Timeout data output pin. Often you want a value (such as the Default value) output when the timeout period expires; to do this, follow these steps, which use a Text Input dialog box:

1. Set the Timeout.

Select Properties from the object menu. Select the Timeout Enabled check box. Set the Pop-Up Duration. Click OK.

2. Add the Default Value data input pin.

3. Select Data [image] Constant [image] Text to input the default value. (Select a Data [image] Constant object appropriate to your needs to input the default value.)

4. Input the default value into the Text object.

5. Connect the Text data output pin to the Default Value data input pin.

6. Select Flow [image] Gate.

7. Connect the data output pin of the Text to the data input pin of the Gate.

8. Connect the Timeout data output pin to the sequence input pin of the Gate. When the timeout period expires, the default value is output through the Gate.

The following figure shows a program that uses a JCT object to output either the entered value or the default value if the timeout occurred. This program is saved as timeout.vee in your manual examples directory.

Outputting a Default Value on Timeout


Building a Custom Dialog Box

When a built-in Dialog Box object doesn't fit your needs, create a custom dialog box. The following topics explain how to create custom dialog boxes from Pop-Up Panels. Once they are created, you add the controls, displays or other objects as needed. If you prefer not to build programs by following the steps below, open the files (via Help [image] Open Example) that contain the dialog box programs and modify them to suit your needs.

To create a Pop-Up Panel, follow the steps in To Build a UserObject Panel. You can make the Pop-Up Panel from either a UserObject or a UserFunction. Unless otherwise specified, the instructions for this group of topics assume the use of a UserObject.


To Build a Basic Dialog Box

1. Once you've built a Pop-Up Panel, follow the steps in To Keep a Pop-Up Panel Displayed twice. The first time to add an OK object so that users can confirm their choices, and the second time to add an OK object to be the Cancel button so that users can cancel their choices.

2. Assign the Enter key to the OK button and the Esc key to the Cancel button.

Select Properties for the first OK object and change the AssignToEnterButton property to True.

Select Properties from the second OK object's object menu. Change the Title to Cancel and change the Assign to [Esc] key check box to True.

Now the OK button is assigned to the Enter key (by default) and the Cancel button is assigned to the Esc key.

3. Select Flow [image] Exit UserObject and place it in the Detail View of the UserObject.

4. Connect the data output pin of the Cancel button to the sequence input pin of Exit UserObject.

5. Select Data [image] Constant [image] Text. (This could be any object to get user input.)

6. Connect the data output pin of the OK button to the sequence input pin of the Text object.

7. Create a data output terminal on the UserObject.

8. Connect the data output pin of the Text object to the data output pin of the UserObject.

9. Select Flow [image] Exit UserObject.

10. Connect the sequence output pin of the Text object to the sequence input pin of the Exit UserObject.

Now the dialog box outputs the value if OK (or Enter) is pressed. No value is output if Cancel (or Esc) is pressed.

The following figure shows the program created using these steps.

A Basic Custom Dialog Box

This program is saved as dialog1.vee in your manual examples directory.

Details about this example:

The OK button must be connected to the Text object; if it was not, the Text object would operate as soon as the UserObject began to run. Therefore, the default data would get propagated to the UserObject output data pin. The OK button prevents the Text object from operating until the user, after typing in the Text object, presses OK.

The threads with OK and Cancel must be connected to Exit UserObject objects. If they were not, the user would have to press both OK and Cancel for data to be output from the UserObject, because a UserObject does not propagate its output data until all objects inside it have finished operating.

To see these execution principles demonstrated, follow these steps:

1. Select the Show Execution Flow toolbar button.

2. Show the UserObject’s edit window in its Detail View.

3. Run the program.


To Set a Timeout

If you want to have the dialog box go away after a period of time, set a timeout. Follow these steps to add a timeout to the custom dialog box created in To Build a Basic Dialog Box.

1. Select Flow [image] Delay and place it in the Detail View of the UserObject.

2. Select Flow [image] Exit UserObject.

3. Connect the sequence output pin of the Delay object to the sequence input pin of the Exit UserObject.

4. Specify the pop-up duration (in seconds) in the Delay edit field. When the time is up, the Pop-Up Panel is put away.

5. Add a second data output terminal to the UserObject.

6. Connect the Delay object's data output pin to the second data output pin to make it available for use in the Main context.

When the timeout period expires, an empty container is output on this terminal.

The following figure shows the program created using these steps.

A Dialog Box With a Timeout

This program is saved as dialog2.vee in your manual examples directory.

When the timeout expires in dialog2.vee, no value is output from the UserObject. Often you want the UserObject to output the default value when it times out as shown in the following figure.

The Default Value is Output When the Timeout Period Expires

This program is saved as dialog3.vee in your manual examples directory.


To Check for Valid Data

The following figure shows a program that checks the input value against some constraint, before outputting the value. If the value does not meet the constraint, another dialog box pops up to inform the user.

A Dialog Box With Constraint Checking

This program is saved as dialog4.vee in your manual examples directory.

The important aspects of this example are:

The Until Break object allows you to retype a number after the Error Pop-Up Panel executes, or to retype a number after the Enter a number... object has already executed once.

The Error Pop-Up Panel is a UserObject Pop-Up Panel that displays a message, and responds to Enter or Esc. It times out after five seconds.


To Build a Self-Modifying Panel

To have a panel present choices to the user based on previous user selections, create a self-modifying panel.

The following figure shows a program that changes the choices in a Drop-Down List, based on the selection made in a Radio Buttons object. The Pop-Up Panel is shown in the upper right of the figure.

A Self-Modifying Panel

This program is saved as dialog5.vee in your manual examples directory.

The important aspects of this example are:

The Select a Product (Radio Buttons) object has Wait for Input set in its Properties window.

Phantom Tests, Beetle Tests, and Viper Tests are Text arrays that contain the list of tests to input to the Select the test to run, Drop-Down List object via an Enum Values control input pin.

Select the test to run has Wait for Input set on its Properties window to hold off sending data to the Gate until a test number is chosen after a product selection.


Building a Status Panel

To display a status panel while your tests run and to update it with current test data, use a UserFunction Panel. Show it with the showPanel object and run it with the Call object.

When you use showPanel, you cannot use Show Panel On Execute (in the UserFunction Properties window). The following table summarizes the differences between the way showPanel and Show Panel On Execute execute.

Differences Between showPanel and Show Panel On Execute

_________________________________________________________________________________________________

showPanel

Show Panel On Execute

_________________________________________________________________________________________________

The panel stays up until a hidePanel object is executed or the program stops. | The panel stays up until the UserFunction is finished executing or the program stops.
The UserFunction is executed with Call, and the panel is displayed with showPanel. Therefore, the UserFunction can be executed multiple times while the panel remains visible. | The UserFunction is executed and the panel is displayed with Call. Therefore, each time the UserFunction is called, the panel is automatically displayed; after the UserFunction has finished executing, the panel is automatically hidden.
The displayed position can be set programmatically at run time. | The displayed position is set manually at development time.
The displayed panel size can be different than the size of the Panel View. | The displayed panel size is the same size as the Panel View.
The user cannot move the panel when it's visible. | The user can move the panel when it's visible.

_________________________________________________________________________________________________

See Also:

L ab 11-5: Creating a Status Panel


To Build a Status Panel

Build a status panel by building a UserFunction Panel as described in To Build a UserFunction Panel. When the UserFunction’s edit window is open, make sure the ShowPanelOnExecute check box is not set in its Properties window.

See Also

L ab 11-5: Creating a Status Panel


To Show a Status Panel

Use the showPanel object to show a status panel.

1. Select Device [image] Function & Object Browser. In the Function & Object Browser, select Built-in Functions, then showPanel.

The showPanel object appears with a formula containing five parameters and their associated terminals for the UserFunction name, position, and size. You can connect objects containing data to the input terminals, or you can edit the parameters directly and delete the inputs.

2. Type the UserFunction name between the quotes, replacing UFname.

3. To specify a location, type the x and y coordinates to specify the position in the VEE window of the UserFunction Panel's upper-left corner. The coordinates for the upper-left corner of the VEE window is 0, 0. The edit field on the showPanel object looks like: showPanel(MyFunc,300,300).

If you do not specify a location, the panel is displayed in the center of the screen.

4. To specify the size of the panel displayed, you must have specified the location. Specify the width and height of the panel in pixels.

If this size is smaller than the existing UserFunction Panel View, the upper-left part of the panel is displayed. If the size specified is bigger than the existing Panel View, the panel displayed has additional area added on its bottom right.

If there is a background picture, it is displayed in the size specified, and is shown according to its display mode. For example, if the display mode is Scaled, the background image is scaled to the size specified in the showPanel object.

When you specify the location and size, the edit field on the showPanel object looks like: showPanel(MyFunc,300,300,100,100).

You can display only one panel for each UserFunction. If you execute a second showPanel, the first panel is hidden and the panel is shown as specified in the second showPanel call.

See Also: L ab 11-5: Creating a Status Panel


To Hide a Status Panel

When the program finishes executing, all panels shown with showPanel are no longer displayed. To hide a panel while the program is running, follow these steps:

1. Select Device [image] Function & Object Browser. In the Function & Object Browser, select Built-in Functions, then hidePanel.

2. Type the UserFunction name between the quotes, replacing UFname. When this object operates, the named panel is hidden.


To Update a Status Panel

The showPanel object only shows the panel; it does not execute the UserFunction. Use the Call object (located in Device [image] Call) to send new data to the status panel and update the display. You can also call the UserFunction from any expression such as in a Formula or a Sequencer object.

You can also use showPanel in any expression such as in a Formula or a Sequencer object. For example, use showPanel as an expression in the first transaction of a Sequencer. As each test runs, the data on the status panel is updated. Use hidePanel in the last transaction of the Sequencer.

After you've sent new data via the Call object, you do not need to call showPanel again; the contents of the displayed panel are updated automatically.


A Status Panel Example

The following figure shows a simple status panel that is updated with information. After you make a choice in the List Box object, the data associated with that test is displayed on the panel.

A Status Panel

The following figure shows the program that displays the status panel. This program is saved as status.vee in your manual examples directory.

A Status Panel Example Program

The important aspects of this example are:

The Record constant sets the record of test results. This could be the log output from a test function.

The Until Break object lets you choose the test information multiple times.

The Get Field object resets the List Box to the value selected in the last iteration.

When the Done button is pressed on the List Box, the status panel is hidden and the Until Break loop is completed.

The UserFunction contains a Panel View that is updated each time the UserFunction is called.

The mfgtest.vee program in the apps examples directory demonstrates a more complete program that uses status panels in conjunction with the Sequencer.

See Also: L ab 11-5: Creating a Status Panel


To Animate Pictures

You can use showPanel and hidePanel to perform animation. Follow these steps to create a simple animation program:

1. Create a Panel View in the Main Window by using Create Panel on the Main Window’s object menu.

2. In the Main Window Properties, change Execution Window Title to A Simple Animation, and be sure to enable ShowPanelonExecute.

From the Appearance Properties, select a background color for the Main Panel.

This color is important, because you'll use that same color for the background of the animation file(s).

3. Create a graphics file of the image you want to animate.

4. Open a UserFunction edit window using Device [image] UserFunction.

5. Select Display [image] Picture, placing the object in the UserFunction window. Specify your graphics file via the Properties window.

6. Add the Picture object to the UserFunction Panel, then from the Picture object menu, select Properties.

7. Turn off the Picture border and title bar, and place the Picture in the upper-left corner of the UserFunction Panel.

8. From the UserFunction object menu, select Properties.

9. Change Title to picture. Turn off the UserFunction Panel's title bar and border from the Pop-Up Panel category.

10. Change the Panel View background color to the Main Panel's background color.

11. Reduce the UserFunction Panel size.

12. Select Device [image] Function & Object Browser, then select the built-in function showPanel, placing it in the Main Detail View.

13. Type the UserFunction name between the quotes, replacing Ufname with picture.

14. Delete the input terminals except for the position parameters x and y.

15. Use the terminal names in the edit field so it looks like showPanel(picture,x,y).

16. Select Flow [image] Repeat [image] For Range.

17. In the For Range object, fill in the range of x and y coordinates, such as From: -20, Thru: 500, and Step: 10.

18. Add the Gate and Delay objects from the Flow menu. Set the Delay value to .05.

19. Connect the For Range output to the Gate input, and the Gate output to the showPanel X and Y inputs.

20. Connect the Gate sequence out to the Delay sequence in. Then connect the Delay output to the showPanel sequence in.

21. Press the Panel button to see the Panel View.

22. Run the program and see how the picture moves across your Panel View.

The following figure shows the program created using these steps, including the UserFunction Panel.

A Simple Animation

This program is saved as animate.vee in your Manual examples directory.

Race: A Simple Animation

The following figure shows a portion of the Panel View of a program that uses simple animation in VEE.

This program is saved as Race.vee in the Games examples directory. The Wheel.vee and Slots.vee programs in the Games directory demonstrate more complex animation.

Using Multiple Images

You can create animations with multiple images by adding a data input terminal to the Picture object, and programmatically inputting the file name to the Picture at run time. When the Picture display mode is Scaled, images take longer to display than if Centered or Actual are selected.


Building a Panel With Non-English Text

To build a panel with non-English text you need to have your environment set up to display non-English characters. There are a few things in VEE that are in English and cannot change on your panel:

Some objects have English text. For example, Data [image] Selection Control [image] Pop-Up List. When the list is popped up, the title of the pop up is Make Selection. The buttons are OK and Cancel.

The menu choices in the Panel View are in English, as are the associated dialog boxes, such as Open, Save, and Save As.

The object menu choices are in English.

After setting the environment to display non-English characters, you can type non-English text in VEE in any place you can type English text. For example, Labels, Constant objects, titles on objects, Confirm (OK) buttons, and Dialog Box objects (and the buttons on them).


Preventing Program Changes

When delivering a program for others to run, you generally don't want to let them modify it. You only want them to observe the program execution and operate any controls. There are two basic ways to prevent accidental modification:

File [image] Create RunTime Version - When you use this command, you save a secured version of the current program to the file filename.vxe, without any side-effect to the current program. Users can run the secured version directly in the VEE RunTime environment. You must create a Main Panel View so that they can see a panel as the program executes. This choice is useful to prevent any access to your source program.

Caution
There is no way to unsecure a secured (.vxe) program; be sure to save an unsecured version of your source program (.vee).

veerun filename - This command is primarily used to run secured VEE programs. However, you can use it to run unsecured programs. When VEE starts, it loads the program in filename, and runs the program in the VEE RunTime environment. As soon as the program is done, the run-time window closes. You must create a Main Panel View so that users can see a panel as the program executes. This is a useful choice if you do not want to maintain two files (a source file and a secured file).

Note

The version of VEE RunTime used to run a program must the same or newer than the version of VEE used to develop the program.


To Prevent Program Changes

The following list contains some tips to use when getting ready to deliver your program:

To prevent users from editing text in Note Pad object(s) added to the Panel View, turn off editing for the Note Pad. In the Panel View containing the Note Pad object, edit Note Pad Properties; in the Appearance category change EditEnabled to False.

To prevent users from changing maximum and minimum values on objects such as Slider, Meter, Thermometer, Fill Bar, and Tank, add control pins for MaxValue and MinValue.

To prevent users from moving UserObject or UserFunction Pop-Up Panels, use the PopupMoveable property on the Properties Window for these panels. Also, you can use a UserFunction Panel instead and display it programmatically with the showPanel object. Refer to Building a Status Panel for details about showPanel.

To prevent users from changing the scale on VEE graphical Display objects, change the Layout. In the Panel View containing the object, select Properties from the object's object menu; in the Layout category, turn off Enable Trace/Scale Editing.

To prevent any of the VEE default colors and fonts on the destination system from being used, save the program with all your default colors and fonts.

1. Select File [image] Save As….

2. Select the Save colors and fonts with program check box.

3. Click Save. All the colors and fonts used in your program are now explicitly saved in your program.


To Secure a Program

Caution: There is no way to unsecure a secured (.vxe) program; be sure to retain your source program (.vee)

If you decide to create a secured version of your program before distributing it, follow these steps:

1. Select File [image] Create RunTime Version.

2. In the Create RunTime Version dialog box, enter the program name. You do not need to enter the file name extension, since .vxe is added automatically.

3. Select Save colors and fonts with program to save all the default colors and fonts in the program file that are selected in the Default Preferences dialog box. This ensures that whoever runs your program will also get all of your default colors and fonts. If this option is not selected, only the colors and fonts explicitly set in your program are saved in your program file. This allows others using your program to retain their own default colors and fonts. If an existing program is loaded, the option is set according to how the program was saved previously.

Save I/O configuration with program is enabled by default. You can un-check this selection if you do not want the embedded I/O configuration. VEE allows you to embed I/O configuration information in the program itself. See Instrument Manager for more information about saving an I/O configuration.

There is no side-effect to the source program. The secured program is saved to a different file name. For example, the unsecured program prog.vee is saved as the secured program prog.vxe.

You can run secured programs in VEE RunTime, which is a run-only version of VEE. You may distribute your program and VEE RunTime on an unlimited number of computers.

Note

If the user must observe or interact with the program as it executes you must create Panel View(s) in the form of a Main Panel View or Pop-Up Panels. If you want your program to run without user intervention, Panel Views are not necessary. However, some sort of status indication is helpful.


To Re-Secure a Program

When distributing a secured program to your users, each time you change the original program, you must save it secured again, and redistribute it. Refer to To Secure a Program.


To Secure a UserObject

When you're distributing a UserObject for others to use, you may want to secure the UserObject to prevent modifications to it. Only the icon view or the UserObject Panel View is available to them. Be sure to create a Panel View if users must interact with the UserObject.

1. Open the UserObject’s Edit Window. From its object menu, select Save Secured Version.

2. In the Save Secured Version dialog box, enter the UserObject’s file name. The .vee extension is added automatically.

If the program containing the UserObject has already been saved, or you've saved the UserObject via File [image] Save Objects, you may not want to save the UserObject again. If you still want to save a secured version, use a different file name.

3. When others want to use the secured UserObject, they select File [image] Merge, and then select the file name of the secured UserObject. They use the secured UserObject in the program just like any other object.


To Include All Needed Files

When distributing your program to other systems, you should embed your instrument configuration in the VEE program. Embedded I/O configuration is the best choice in most cases. If the I/O configuration is not embedded in the program, it can be edited on the target system; see To Configure VEE Pro RunTime.

Files you must include with your program (if you use them) are:

Data files.

*.cid files for instrument drivers you've written.

*.cid files for instrument drivers not installed on the destination system.

VXIplug&play instrument drivers.

IVI-COM drivers.

Graphics files you've created.

DLLs or compiled functions that you call.

Additionally, you must include the .NET Framework redistribution package (dotnetfx.exe) and it must be installed before the runtime is installed. If the .NET Framework is not installed, the VEE Pro runtime product does not install .

Once you have the required files together, you can copy them to other systems. If your program controls instruments, you must also install the Agilent I/O Libraries Suite version 15.0 or higher.

Putting all files on distribution media

You can create distribution media containing VEE Pro RunTime, which you can include with your program.

1. Copy all of your program and supporting files onto a disk.

2. Copy the VEE Pro RunTime setup files from the VEE CD-ROM to a CD-R or Zip disk. The files are on the VEE CD-ROM, in the subdirectory runtime.

3. Copy the Agilent I/O Libraries Suite (version 15.0 or higher) to another CD-R (if your program controls instruments).

4. Prepare your product’s documentation.

You are responsible for explaining installation procedures to your end-user or customer about how to install all of the files from your distribution disks. For VEE Pro RunTime, the runtime subdirectory contains the setup.exe program that installs the product and the dotnetfx.exe file that installs the .NET Framework.

For more information about VEE Pro RunTime, see About the Agilent VEE Pro RunTime Product.


To Create an Application Icon in Windows

To Create an Application Icon

It is convenient for your users to double-click on a program icon to run your VEE program. To set up the icon, follow the steps below on the destination system. For details about these procedures, refer to the MS Windows documentation and online help.

You can place a shortcut to the program on the desktop or in the taskbar’s Start menu. The steps are similar for a secured or unsecured program. However, be sure to use the veerun command in the shortcuts to run an unsecured program. This prevents access to the source.

A desktop shortcut

1. In Windows Explorer, click on your program’s file name with the right mouse button, then select Create Shortcut. The file name Shortcut to filename appears in the list.

2. Drag the shortcut file name to the desktop. A shortcut icon appears.

3. Change the shortcut command for an unsecured program (.vee) to include veerun in the Target command. A secured program (.vxe) automatically uses veerun; you only need to change the command if you want to use any veerun options.

a. Click on the shortcut icon with the right mouse button, then select Properties. The Shortcut Properties dialog appears.

b. On the Shortcut tab, change Target to look something like this:

"C:\Program Files\Agilent\VEE Pro RunTime 8.0\veerun.exe" MyApp.vee

Be sure to include the quotation marks, and any veerun options you need. For a list of command-line options, see To Start Agilent VEE with Command-Line Options.

If the path for Start in is correct, you do not need to specify the program’s path in Target.

c. Click OK.

4. To change the shortcut icon’s label, click on the icon, then click on the label. Type in a new label. Double-click the shortcut to run the program.

A Start menu shortcut

1. On the Windows task bar, click Start [image] Settings [image] Taskbar.

2. In the Taskbar Properties dialog box, on the Start Menu Programs tab, click Add. The Create Shortcut dialog appears.

3. Enter the command to run your program. Use quotation marks if you type in the command.

For an unsecured program (.vee), include veerun and your program’s file name with their respective paths. A secured program (.vxe) automatically uses veerun, so the command only needs to include the program file name and path. The command for an unsecured program should look something like

"C:\Program Files\Agilent\VEE Pro RunTime 8.0\veerun.exe" "C:\Document and Settings\[username]\My Documents\VEE Programs\MyApp.vee"

Include any veerun options that you need. For a secured program, you need to include veerun in the command to use options. For a list of command-line options, see To Start Agilent VEE with Command-Line Options.

Click Next. The Select Program Folder dialog appears.

4. Select the folder to place the shortcut in. You can select an existing folder or create a new one. Click Next. The Select a Title for the Program dialog appears.

5. Enter a useful name for the program’s shortcut. This name will appear on the Start menu. Click Finish.

6. Click OK. Select Start [image] Programs to use the shortcut.

See Also

To Start Agilent VEE with Command Line Options


Example: Sequencer Transactions

The Sequencer object in its open view shows a list of sequence transactions. Each transaction is similar to the other types of transactions. The program below shows how the Sequencer uses transactions to execute expressions and call functions.

This program does not show two UserFunctions in the background: myRand1, which adds a random number from 0 to 1 to the value of its input, and myRand2, which adds a random number from 0 to 100 to its input. You see the calls to these UserFunctions when you expand the transactions. For further information on creating and using UserFunctions, see Help [image] Contents and Index [image] How Do I... Create Custom Objects and Functions [image] Creating and Using UserFunctions.

When you click a transaction, a dialog box "expands" the transaction so you can view and edit it. The dialog box below shows the first transaction, test1:

A sequence transaction can be either a TEST transaction or an EXEC transaction. In this transaction, the type is TEST:, the name field is test1, the nominal specification is 1.25, a RANGE: specification is used, and the range is 1 <= ... <= 1.5.

Only values from 1 to 1.5 will pass the test. The expression myRand1(A) calls the UserFunction, using the value on the A input terminal of the Sequencer as its input parameter.

The transaction has logging enabled so a local variable named Test1 is automatically created to contain the log record of the results of this test. This log record will also be available as part of the Log output terminal. The IF PASS and IF FAIL conditions are both set to THEN CONTINUE. This means that, pass or fail, when test1 is done the next transaction, test2, is executed.

The DESCRIPTION field is a comment area for this test.

NOte

The SPEC NOMINAL value is not used for RANGE or LIMIT tests except for "documentation" purposes. However, if you use tests based on TOLERANCE or %TOLERANCE values, the tolerance will be calculated relative to the SPEC NOMINAL value.

The second transaction, test2 is also a TEST transaction.

This second test is similar to the first. The UserFunction myRand2 is called with the expression myRand2(A). The resulting value is tested to see if it is in the range 1 through 51, with a nominal specification of 26. Again, pass or fail, the Sequencer continues to the next transaction.

The third transaction is an EXEC transaction:

An EXEC transaction, unlike a TEST transaction, performs no comparison of the function result to a specification or range. EXEC transactions are used to perform an action that does not require a pass/fail test.

For example, an EXEC transaction could call a routine that sets up an external configuration before a TEST transaction is performed, or it could execute a power down procedure after a series of tests. (An EXEC transaction is a shortcut for specifying an "always pass" test condition.)

In this example, the transaction named finish returns the value of B to the Return output terminal of the Sequencer object. Since no test is performed, logging does not occur for an EXEC transaction.

You can use the DESCRIPTION field to briefly describe any transaction.

When you run the program, the three transactions are executed in sequence as shown below.

The logged test results are output on the Log output terminal and displayed. The results are logged as the Record data type, a record of records. In this case, test1 has passed with a value of 1.396 and test2 has failed with a value of 85.05. The third transaction returns the value on the B input, which is the string Done!.

Each transaction that has logging enabled creates a log record named as the transaction name. In this example, logging is enabled for the first two tests so local variables named Test1 and Test2 contain the log records for those transactions.

The fields contained in the log records are defined in the Properties dialog box. To access the logging configuration, click Properties in the Sequencer object menu, then click the Logging tab. By default, log records contain Name, Result, and Pass fields.

The Test1 and Test2 local variable names can be used in any expression within the Sequencer to access the results of the current or a previously executed transaction. For example, Test3 could have called a function with Test1.Result as a parameter to pass the result of the first test. Or Test2.Pass could be used as an expression that would evaluate to 1 if Test2 passed, or 0 if Test2 failed.

There is one more local variable, thisTest, available to access the logging records. The value of thisTest is always the same as the logging record for the currently executing transaction. This allows you to write transaction expressions that can be used in many transactions without having to include the name of each transaction.

The data structure produced by the Log output terminal on the Sequencer is a record of records, as shown below.

The record produced by the Log output pin contains a field for each transaction that has logging enabled, Test1 and Test2 in this example. Each of these fields is the log record for the specified transaction, containing the fields Name, Result, and Pass.

This record of records is available on the Log output pin and can be used by other objects by using the record "dot" syntax. For example, the expression Log.Test1.Result would, in this case, return the value 1.396, as shown in the figure above. Likewise, Log.Test1.Name would return test1 and Log.Test1.Pass would return 1.

The data logged on the Log output pin is always the data from the last execution of each transaction. If you want to log the results of every execution of each transaction, set Logging Mode to Log Each Transaction To: on the Logging tab of the Sequencer Properties dialog box. This option calls the specified function (or expression) at the completion of every transaction.

This option can also be useful if you want to log test results to a file or printer as they happen, rather than waiting until the Sequencer has completed. The local variable thisTest can be used as a parameter to the logging function to pass the log record of the transaction that has just completed.

See Also

Sequencer, Example: Bin Sort, Example: Logging Test Results, Example: Logging to a DataSet, The Sequencer Object


Example: Logging Test Results

The following figure shows an example of logging test results, where an iterator causes the Sequencer to repeat the tests over and over and to log the results.

In this example, the For Count object causes the Sequencer to execute its series of tests (test1 and test2 of the previous example) four times. For example, if four "widgets" are being tested on an assembly line, each execution of the Sequencer tests one widget.

The resulting series of records from the Log output terminal is collected by the Collector and displayed as an array of records. You can use the To File object to output this array to a file using a WRITE CONTAINER I/O transaction, or you can use a DataSet.

You can think of the output of the Collector in this example as an array of records of records as follows.

Each array element (Log[0], Log[1], etc.) represents a single iteration of the sequencer and is a record of records. The logged output is available for analysis in expressions. In this case, Log[*].Test1.Result is a "core sample" from the array. In fact, Log[*].Test1.Result would return an array of values (1.396, 1.353, 1.319, and 1.016 for the example results).

note

The logged array is not a three-dimensional array but an array of records of records. This is important because the individual fields of a record can be of differing data types. While the Name field is Text, the Result field could be a Waveform, etc. Also, the Test2.Result field could be a Waveform while the Test1.Result field is a Real value.

However, each individual field must be of a consistent data type throughout the array. For example, the field Test1.Result cannot be a Real value for Log[0] and a Waveform for Log[1].

The example below extends the example above to 10 iterations of the Sequencer and adds some analysis of the logged data. The expression log[*].test1.result in the Formula object returns a 10-element Real Array that contains the results of test1. This array is then statistically analyzed by means of the min(x), max(x), mean(x), and sdev(x) objects.

This example is saved in the file manual44.vee Manual44.vee in the examples directory.

See Also

Sequencer, Example: Bin Sort, Example: Logging to a DataSet, Example: Sequencer Transactions, The Sequencer Object


Example: Logging to a DataSet

You can use a DataSet to store logged test results. In the program below, the Sequencer object Log output terminal is connected to the To DataSet object.

When the For Count object is finished, it causes the From DataSet object to retrieve the stored DataSet (myDataSet). From DataSet is configured to retrieve ALL records from myDataSet but to test each record against the condition Rec.test1.pass AND Rec.test2.pass. A particular record is retrieved only if both test1 and test2 passed for that record.

Of the retrieved records, if any, the expression Rec[*].test1.result returns all of the test1.result record fields, which are then statistically analyzed. (This program will error if none of the records satisfy the expression Rec.test1.pass AND Rec.test2.pass.)

This example is saved in the file Manual45.vee in the examples directory.

See Also

Sequencer, Example: Bin Sort, Example: Logging Test Results, Example: Sequencer Transactions, The Sequencer Object


Example: Bin Sort

The next example measures the resistance value of carbon resistors.

Previously, carbon resistors were manufactured by a rather imprecise process, then tested, sorted, and marked. The standard resistance values (such as 220W, 270W, and 330W) were chosen to overlap at 10% tolerance so each resistor could be used. If the resistor value is more than 10% greater than 220W, it can be labeled as a 270W ohm resistor, etc.

The following figure shows a program in which the Sequencer calls a UserFunction, which returns a resistance value. The Sequencer then runs a series of tests to determine which nominal resistance value and percent tolerance the resistor satisfies. This is a "bin sort" problem. That is, the sequencer returns a result that identifies the bin in which to put the resistor.

One of the advantages of using the Sequencer to call a UserFunction is that different UserFunctions can be substituted. For this example, we use a UserFunction (simResist) that returns a random resistance value in the expected range during development. You could substitute another UserFunction that executes Instrument I/O and returns real resistance values.

The simplest solution to the problem is to use an extended series of sequence transactions, each testing the resistance value against a nominal value and tolerance.

In this example, the first sequence transaction (test1) calls the UserFunction simResist with the expression simResist(). (This UserFunction requires no inputs). Here is the first sequence transaction.

test1 tests to see if the resistance value returned by simResist is within ±2% of the nominal value, 330W. If it is, the two-element Real array [330 2] is returned on the Return output terminal, and the To String object converts this value to the string 330 Ohm, 2%. If the test fails, the Sequencer goes to the next test.

The second transaction, test2, works like test1 except that instead of calling simResist again, the FUNCTION field contains the expression test1.result. This is the second sequence transaction.

note

Any transaction with logging enabled creates a "local" Record variable with the same name as the test. This record contains the fields specified for the logging record. For the transaction test1 the expression test1.result returns the value returned by the function called in test1.

There are two reasons for using the expression test1.result in this example. First, by using test1.result in transactions test2 through test9 we can ensure that each transaction uses the same function result, even if we later change test1 to call a different function.

More importantly in this example, each time you call the UserFunction a new resistance value is returned. Instead of a new value, we want to continue testing the original resistance value against successive nominal values and tolerances. So, the transactions test2 through test9 all include the expression test1.result in the FUNCTION field. These transactions work like the first, returning the appropriate array ([330 5], [330 10], [270 2], etc.) if passed.

The first eight tests continue to the next test if failed. However, we need an indication if all the tests are failed. Thus, test9 is configured IF FAIL THEN ERROR. The Error output terminal causes the AlphaNumeric display entitled Error Condition to execute, displaying the text Out of Range.

Although this approach is simple, it is not very efficient. You would need to create quite a large number of sequence transactions to test several resistance values, with three tolerances in each case. The following figure shows an improved version of the "bin sort" example.

This example is saved in the file Manual46.vee in the examples directory.

Some key points for this program are:

• This program uses two Sequencer objects. The first one (labeled Test Bounds) "re-uses" the tests in the second one (labeled Test Value & Tolerance).

• The Real64 array in the upper left corner of the program contains five elements, each representing a standard resistance value. However, the list of values is extensible in this example. Regardless of the number of array elements, the TotSize(x) function returns that number so the For Count object will iterate the correct number of times. The expression R[i] in the Formula object takes care of the indexing.

• In the Sequencer named Test Bounds, the first transaction (test1) calls the UserFunction simResist with the expression simResist() as follows.

A simulated resistance test value is returned and tested to see if it is at least 90% of the lowest value (150W) in the array. (Any value field in a sequence transaction can contain an expression such as min(a)*.9.)

The second transaction (test2) tests to see if the value (test1.result) is less than or equal to 110% of the highest value (330W) in the array. The following figure shows this transaction.

If either test fails, an error occurs.

• If an error does occur, the UserObject named Error Condition uses a Triadic expression to ascertain whether to display Out of Range: LOW or Out of Range: HIGH. The UserObject is configured as Show Panel on Exec so if either error condition occurs a display "pops up" to show the error. This happens once every few times you run the program because the UserFunction simResist returns random values in the range 100–400. (To continue, press OK in the pop-up box.)

• The transaction test1 in the first Sequencer is the only transaction that calls the UserFunction simResist. (test2 includes the expression test1.result instead of simResist.) This is necessary in this case because we want to run multiple tests on just one resistance value. Otherwise, a new value would be returned every time the UserFunction was called. However, there is another reason.

Since the UserFunction simResist is only called once, you can replace it with a call to a different UserFunction. The example (manual46.vee) contains a second UserFunction, called measResist, which uses a Panel Driver to call an HP 3478A Digital Voltmeter configured for resistance measurements. If you have an HP 3478A meter, connect it via GPIB, change the FORMULA field in test1 to the expression measResist(), and run the program.

• Regardless of whether simulated or measured resistance values are taken, the Test Bounds return value is displayed and is set as a global variable (globalOhms). For example, the three transactions in the Sequencer labeled Test Value & Tolerance each call this global variable using the expression globalOhms. The following figure shows the first transaction expanded.

If a test passes, the appropriate real array (e.g., [220 2]) is output. The To String object converts the data to a string (e.g., 220 Ohm, 2%). The Sequencer is executed as many times as necessary until a Bin Sort result is found.

• Since we are not using the Log output terminal in either Sequencer, we have deleted the terminal to speed up execution.

• If you want to see the flow of this program, try running it a few times with Show Execution Flow and Show Data Flow turned on.

For some further examples using the Sequencer, see the examples directory.

See Also

Sequencer, Example: Logging Test Results, Example: Logging to a DataSet, Example: Sequencer Transactions, The Sequencer Object


Understanding the VEE Execute Program Object

To Understand the VEE Execute Program Object

In addition to ActiveX Automation, there are two ways to run programs in other languages from VEE:

1 Use the Execute Program object to escape VEE and run another program, application, or operating system command. This method is the most versatile and easy to use.

2 Link compiled functions in other languages to VEE through Dynamic Link Libraries on the PC. Although this is slightly more difficult to execute, it gives you significant performance gains. For more information about Dynamic Link Libraries, refer to Using Dynamic Link Libraries.

The Execute Program object is located in the I/O menu. Notice that the Execute Program object does not use transaction I/O to communicate with programs, so you do not add data input and output pins to pass data to the compiled program.

See Also

Execute Program, To Use the Execute Program Object, To Use a System Command, To Write Programs That Port Easily.


Using the Execute Program Object

To Use the Execute Program Object

Following figure shows the Execute Program Object on the PC.

Use the Execute Program object to run the following from VEE:

• Compiled programs written in other languages

• *.BAT or *.COM files

• MS DOS system commands, such as dir

• Any document or URL with a recognized extension. The “open” action is invoked in the files. If an “open” action does not exist, the default action is invoked with the file. An example of a URL would be http://www.agilent.com/find/vee.

The fields in the Execute Program Object are:

Field Name

Description

Run Style

Determines the window size. Normal specifies a standard window, Minimized specifies an icon, and Maximized specifies the maximum window size. The Working directory is the directory that holds any files related to the program.

Wait for prog exit

Specifies when to fire the sequence pin.

• When set to Yes, the sequence pin is not fired until the program finishes executing.

• When set to No, the sequence out pin fires before the specified program is done executing.Note that when launching documents or URLs, if the document or web site is loaded into an application that is already running,VEE does not wait until the application exits.

Prog with params

(Program with parameters) This field holds the same words you would type at a DOS prompt. For example, to run a program in C, enter the executable file name - myprog.exe. (You can omit the .exe extension.)

• If the program has parameters, they would follow the executable file name preceded by a hyphen, such as
myprog -param1 -param2.

• For Windows Vista, Windows XP, and Windows 2000, enter the command cmd /c <system command>

This option tells the command interpreter to read the string following the /c as a system command.

See Also

Execute Program, To Use a System Command, To Write Programs That Port Easily


Using a System Command

To call a compiled program in another language, you can type in the executable file and any parameters in the Execute Program object.

However, to execute an MS DOS system command, you must first run the DOS command interpreter. See Lab: Using a System Command.

See Also

Execute Program, To Use the Execute Program Object, To Write Programs That Port Easily


Writing Programs That Port Easily

VEE includes system information objects in Function & Object Browser [image] System Information as follows. These objects can also be used as functions.

The system information functions in the Function & Object Browser that are commonly used to enhance program portability are as follows:

Function Name

Description

installDir

Specifies the VEE installation directory.

whichOS

Determines the operating system and sends out one of the following strings: Windows_98, Windows_2000, Windows_NT, Windows_ XP.

The program can branch based on these results when incorporating programs in other languages. For example, look at manual49.vee in the examples\manual directory to see a program that uses whichOS() to make sure it imports the right type of library. On a PC, it would import a Dynamic Link Library.

whichplatform

Determines the hardware system on which VEE is running, then returns a string indicating that platform.

whichVersion

Specifies the VEE version, which is useful for program maintenance and debugging.

See Also

Execute Program, To Use the Execute Program Object, To Use a System Command


Including a MATLAB Script Object in Agilent VEE

To Include a MATLAB Script Object in Agilent VEE

When you use a MATLAB object in a VEE program, it looks like a VEE Formula object. There are two ways to add a MATLAB Script object to a program:

1 Select Device [image] MATLAB Script and click to place the object in the program. This creates a default MATLAB Script object that you can edit for your purposes.

2 Select Device [image] Function & Object Browser, and select MATLAB Functions. Choose a predefined MATLAB function and click Create Formula. Click to place the object in the program. Following figure shows some predefined MATLAB functions that could be added to a VEE program.

Notice that each object is named MATLAB Script<function name> to help you distinguish it from other VEE formula objects. Each object already includes the function it will perform, and the input and output pins that are likely to be needed, just like built-in VEE formula objects. You can also edit MATLAB Script objects exactly as you can edit any other VEE object.

note

For more information about MATLAB functions, from the main VEE window, select Help [image] MATLAB Script [image] Help Desk.

See Also

To Work with Data Types Using MATLAB Script in Agilent VEE MATLAB Script.

Copyright (c) 1991-2006 Agilent Technologies, Inc.


Working with Data Types

Only a subset of the VEE data types are supported as inputs and outputs of MATLAB objects.

VEE automatically converts some one-dimensional arrays to make it more convenient for programs that contain both VEE and MATLAB functions. For example, a VEE one-dimensional text array will automatically convert to a two-dimensional character array when it is input to a MATLAB Script object, and a character one-dimensional array from a MATLAB Script object will automatically convert to a Text Scalar when it is output from the MATLAB Script object.

note

For a complete listing and description of the automatic conversions between VEE data types and MATLAB data types, refer to MATLAB Script.

You can also use input terminal data type constraints to ensure that the data input from another object is converted to a supported type, as shown in the following example.

1 Select Data [image] Constant [image] Int32 and click to place the object. Change the value to 7. Clone the object and place the second Int32 under the first. Change its value to 20.

2 Select Device [image] MATLAB Script and place the object to the right of the constant objects.

3 Select Display Alphanumeric and place it to the right of the MATLAB Script object.

4 Connect the output pin from the top Int32 object to the input pin A of the MATLAB Script object. Connect the output pin from the bottom Int32 object to the input pin B of the MATLAB Script object. Connect the output pin from the MATLAB Script object to the input pin of the Alphanumeric object.

Run the program. It generates a VEE Runtime Error stating the expected input was a Real64, Complex, Waveform, or Text, and Int32 input was received instead.

To avoid errors like this, change the input terminal data type on the MATLAB Script object.

5 Double-click on terminal A to open the Input Terminal Information dialog box. Click on Required Type: to display the drop-down menu, select Real64, and click OK. Double-click on terminal B and change it to a Real64 as well.

6 Run the program. Now the Int32 data is automatically converted to Real64 on the input pin before it is passed to MATLAB.

See Also

W orking with Data Types Using MATLAB Script in Agilent VEE MATLAB Script.


Choose a MATLAB to Use in VEE

VEE is shipped with the MATLAB® Script engine, which gives users direct access to the core set of MATLAB functionality, such as advanced mathematics, data analysis, and scientific and engineering graphics.

The MATLAB Script is only a subset of the standard, full-featured MATLAB from The MathWorks. If you have a full-featured MATLAB installed on your machine, then it is easy to use the full power of the MATLAB in VEE programs.

To use the full-featured MATLAB in VEE

1. On the File menu, click the Default Preferences.

2. Click the MATLAB tab.

3. Under the MATLAB tab, click the MATLAB version you want to use.

4. Click the Save button, this will close the Default Preferences dialog box.

5. Save your current VEE program and restart the Agilent VEE.

Please note that after changing the MATLAB used in the Default Preferences dialog box, you must save the change and restart the Agilent VEE to let the changing take effect.

NOTE

You can only use the MATLAB® Script engine shipped with VEE unless you have installed other version of MATLAB.

See Also

MATLAB Script, Using MATLAB Script in Agilent VEE, Using Built-In Math Objects, Working with Data Types.


To Use ActiveX Automation

Listing ActiveX Automation Type Libraries

To find the automation objects installed on your computer, click Devices [image] ActiveX Automation References.

note

For information about ActiveX Control References, refer to How do I ... build an Operator Interface in the Contents and Index under Help menu. Refer also to the “Active X Automation Server”

Devices [image] ActiveX Automation References lists the Type Libraries that are installed on your PC. Each application and ActiveX Component that can be an Automation Server registers a Type Library. VEE displays what is available on your PC. These libraries include information about the functionality of the application or component that is exposed to ActiveX clients.

Type libraries typically consist of a set of classes. Some classes can be created by the programmer. Other classes are always created by the application or component. Classes consist of properties, methods, and events, although not all have to be present. The Type Library provides both the programmer and the VEE environment with information necessary to utilize the application or component using ActiveX interfaces.

When you put a check next to a Type Library in the ActiveX Automation References box, the library objects become available for use in a VEE program. For example, in following figure, Microsoft Excel 9.0 is checked.

Creating and Using ActiveX Programs with Agilent VEE

VEE includes a data type called Object for ActiveX programs. A VEE object with the data type specified as Object is a pointer to something or some data held by the Automation Server. For example, an Object could point to a worksheet inside MS Excel, or to a cell inside that worksheet. (Technically, an Object is a pointer to an IDispatch interface returned by MS Excel or the Server.)

For example, if you select Data [image] Variable [image] Declare Variable, set the Name to App, and set the data type as Object, you can use the variable App to point to an ActiveX Automation object such as the Excel Automation Server. Following figure is an example of a data type Object.

Performing Operations Using ActiveX Statements

To communicate with an ActiveX Automation server, such as the Excel Automation Server, enter ActiveX commands in a VEE Formula object. The following example shows a VEE Formula object that has been named Set Up Excel Worksheet. It contains a list of commands to set up an Excel worksheet to display the results of a test.

The above example use standard Microsoft Visual Basic syntax to create the commands or statements. The commands or statements perform three types of operations: get properties, set properties, or call methods.

• Get property statements usually refer to getting some type of data. The syntax is <object>.<property>. For example, sheet.application gets the application property of the sheet object.

• Set property statements usually refer to setting some type of data equal to something. The syntax is <object>.<property> = <property type>. For example, object.property = MaxSize sets a property.

• Call methods call a method. A method requests the object to perform an action. Methods have parameters that allow data to be passed in and returned. The syntax is <object>.<method>(parameters).

note

The syntax for data type Objects looks similar to the VEE syntax for getting a Record field, rec.field, and calling a UserFunction, myLib.func(), so it is important to assign descriptive names to variables.

Using CreateObject and GetObject

Notice that one of the statements in Set Up Excel Worksheet in Previous section contains the CreateObject() function call. CreateObject() and GetObject() are functions in the VEE Function & Object Browser, and they are designed specifically to return a pointer to an ActiveX object in VEE.

For example, CreateObject("Excel.Sheet")starts up Excel and returns a reference to a workbook in it. (The Microsoft statement “sheet” returns a workbook.) Use GetObject() to get something or some data that already exists in a running Excel, or to load a file into a running Excel.

CreateObject and GetObject are located under Device [image] Function & Object Browser [image] Built-in Functions [image] ActiveX Automation. Following figure is an example of CreateObject and GetObject.

See Also

Lab 6-1: Sending Agilent VEE Data to MS Excel

Lab 6-2: Creating an Agilent VEE to MS Excel Template

Lab 6-3: Using MS Word for Agilent VEE Reports


Introduction to the VEE Excel Library

In May of 2005, Agilent acquired the Vxl product from PASS Technologies Inc. Now known as Excel Library, it is a library of UserFunctions that create a transparent link between Microsoft Excel and VEE. Where it was often a struggle to use ActiveX to get basic functionality with Microsoft Excel in the past, it is now very easy to move data between VEE and Microsoft Excel, use Microsoft Excel charts, and format Microsoft Excel data.

The VEE Excel Library requires Microsoft Office 2000 or later.


To Initialize the VEE Excel Library

Before the VEE Excel Library can be used, the library of UserFunctions must be imported, which is what Initialize does.

Location

On the VEE main menu at Excel [image] Initialize Excel Library


To Set VEE Excel Library Session Defaults

The Settings UserObject is used to define the default values for a VEE Excel Library session. The UserObject has two objects, Call xlLib.Settings and Record.

Open View Parameters

The Record object defines the settings and the Call xlLib.Settings object calls a UserFunction that implements them. The open view parameters for the Record object are listed below.

  • Visible -- Makes Microsoft Excel visible during VEE Excel Library operation. Set this to False for operator interfaces where you want to focus the user's attention on the VEE program. The default is Visible. Print Preview also makes Excel visible.

  • WindowMode -- This refers to the Microsoft Excel program window. The options are Normal (Microsoft Excel window is open but not maximized), Minimized, and Maximized. The default is Normal.

  • BookWindowMode -- This refers to the Microsoft Excel workbook window of the selected workbook. The options are Normal (workbook window is open but not maximized), Minimized, and Maximized. The default is Normal.

  • ArrangeWindows -- If you have multiple workbooks open this will arrange the order of their display. The options are Cascade, Horizontal, Tiled, or Vertical. This parameter is only available when BookWindowMode is set to Normal. The default is Cascade.

  • Error Action -- This determines how VEE Excel Library handles error conditions. The default is RaiseError. The options are:

  • RaiseError -- VEE Excel Library raises the error within its error handler. This is the recommended setting.

  • Quit -- VEE Excel Library closes all workbooks; if the workbook has not been saved prior to the error, the new data is lost. Finally, VEE Excel Library unloads the Microsoft Excel session.

  • OKCancel -- A message box appears that has a 30 second timeout. If you choose OK, the error is ignored. If you choose Cancel, the error is raised. If the timeout expires, the error is also raised.

  • Ignore -- The error is ignored. It is possible the error will occur again, so this option is best used when the user can intervene.

  • DisplayAlerts -- The default setting is True. This allows the Microsoft Excel message box dialogs to be displayed as they appear. To reduce the number of these dialogs, choose False. Caution: Setting DisplayAlerts to false may cause Microsoft Excel to hang. If you are attempting to handle Microsoft Excel overwriting prompts, see the 'Save Workbook As' object.

Notes

These settings are applied to the selected workbook when using Select Workbook.

Settings are not applied to Open Workbook or New Workbook when these entries follow the Settings entry. Only when Settings follows an Open or New does it affect them and then only the immediate workbook.

While creating and debugging your program, you should have the Settings -> Visible parameter set to True. If your program fails or does not quit the Microsoft Excel session properly, you could have multiple Excel sessions active. These sessions use up quite a bit of memory and can cause Excel to act erratically. If this occurs, delete the unwanted sessions using the Windows Task Manager.

Location

On the VEE main menu at Excel [image] Settings


To Quit the VEE Excel Library Add-In

The Call xlLib.QuitExcelLibrary object calls a UserFunction that closes all workbooks, unloads the Microsoft Excel session, and deletes the VEE Excel Library add-in.

Caution: When you quit Excel Library, there is no automatic saving of workbooks. You should call Save All Workbooks or Save Workbook As to avoid losing any changes to the Excel workbooks you have been modifying.

Notes

If the Excel Library is not deleted, Microsoft Excel processes are sometimes left running.

Location

From the VEE main menu at Excel [image] Quit Excel Library

See Also Releasing ActiveX References


To Open a New Workbook

The Open New Workbook menu option is used to create a new Microsoft Excel workbook.

Use

The Call xlLib.NewWorkbook object calls a UserFunction that creates a new Excel workbook. The workbook has the default name for that Book, for example Book8. If you want to ensure the workbook is named appropriately, follow the xlLib.NewWorkbook object with a SaveWorkBookAs object or use the SelectWorkbook to select the workbook later in your program and then use SaveWorkBookAs.

Location

From the main menu at Excel [image] New WorkBook

See Also

To Save a Workbook to a New Name and Format, To Open an Existing Workbook

Lab 8-1: Working with Workbooks


To Open an Existing Workbook

Open a Workbook opens a Microsoft Excel workbook file.

Open View Parameters

The Open Workbook menu selection contains an object, File Name Selection, and a UserObject OpenWorkbook. Within the OpenWorkBook UserObject, there is an object, Open Workbook, and a call to a UserFunction, Call xlLib.OpenWorkbookRW.

The File Name Selection object is a standard object found at Data [image] Dialog [image] File Name Selection. See VEE's online help for more information about this object.

The open view parameter for Open Workbook is:

  • ReadOnly -- This sets whether the file is opened read-only or writable. Possible values are True or False. The default is False.

Location

From the VEE main menu at Excel [image] Open Workbook

See Also

To Open a New Workbook and File Name Selection

Lab 8-1: Working with Workbooks


To Save a Workbook

The Save Workbook menu item saves the workbook by overwriting itself.

Use

The Call xlLib.SaveWorkBook UserFunction saves a workbook. The existing workbook file is overwritten.

Note: This is not a 'save all workbooks' function. It only saves the active workbook.

Caution: If Settings [image] DisplayAlert is set to False, you are not prompted when you overwrite the existing file.

Location

From the VEE main menu at Excel [image] Save Workbook

See Also


To Save a Workbook to a New Name, Format, or Location

This feature can save the active workbook with a new name, a new format, or to a new location.

Use

The SaveWorkbookAs UserObject is used to save a workbook with a new name, to a new format, or to a new location. Follow a Select Workbook with a call to Save Workbook As. Save Workbook As only works with the active workbook.

On the input pin of SaveWorkbookAs, set a text constant or formula with the full path and filename (including filename extension). This will be the new file name.

Caution: If the Settings object has DisplayAlerts set to False, it is possible to overwrite existing files without a warning dialog from Microsoft Excel.

There are two objects available in the open view: Call xlLib.SaveWorkbookAs and Workbook Type.

The Workbook Type record has a Workbook Type button. The Workbook Type options are:

  • Normal -- Normal is used for saving files to Microsoft Excel versions 2000 and above.

  • CSV -- Comma separated value file. This file has the same characteristics as the Text file except the column delimiter is a comma.

  • MSDOSCSV -- MS-DOS comma separated value file.

  • WINDOWSCSV -- Windows comma separated value file.

  • Text -- The text file format saves the text and values displayed in the cells of the active worksheet. Columns of data are tab delimited, and each row of data ends in a carriage return. Cells containing a comma are enclosed in double quotation marks. All formatting, graphics, objects, and other non-text worksheet contents are lost. All rows with data and all characters in each cell are saved. If a cell has a formula but no value, the formula is saved as text. The euro symbol is converted to a question mark.

  • TextPrinter -- Outputs a text file that is printer ready. Within the new text file, the data has the same relative position as it did in the spreadsheet. All other rules apply as noted for Text output.

  • Excel9795 -- Outputs spreadsheet data in a format that is compatible with Excel 97/95.

  • xlHTML -- xlHTML is a converter that changes Excel spreadsheet data into HTML.

Notes

If you attempt to SaveAs to the same filename, you get a dialog. If you select no, you get a VEE run-time error. To avoid this error always provide a unique name or use the VEE To File object under I/O menu. Use the To File with an Execute Delete transaction before writing to the file to prevent the error and to prevent the dialog from appearing and requiring user interaction.

Location

From the VEE main menu at Excel [image] Save Workbook As

See Also

Lab 8-1: Working with Workbooks


To Select a Workbook

This UserObject selects a Microsoft Excel workbook from the currently open workbooks.

Use

Open a workbook with an Open Workbook object or a New Workbook followed by a Save Workbook As object. Later in the program, use the SelectWorkbook object to select the workbook you want to work with. On the input pin, place a text constant or a formula with the full name of the workbook you are selecting. The workbook name can be the full pathname of an opened workbook or workbook name (including the .xls filename extension) or the workbook name of an added workbook such as "Book1".The workbook you select becomes the active workbook.

Notes

The VEE Excel Settings are applied to the selected workbook.

For debugging purposes, you may want to enumerate the workbooks. This feature lists the workbooks that are currently open and is a good way to tell if the workbook you are selecting is even available. See Enumerations [image] Enumerate Workbooks.

Location

From the VEE main menu at Excel [image] Select Workbook

See Also

Lab 8-1: Working with Workbooks


To Close Workbooks

Close a Workbook and Close All Workbooks are used to close one or all Microsoft Excel Workbooks that are open.

Use

Close Workbook is used to close the currently selected workbook whereas Close All Workbooks ends all open workbook sessions.

Caution: When you Close Workbooks, there is no automatic saving of them. You should call Save All Workbooks or Save Workbook As to avoid losing any changes to the Excel workbooks you have been modifying.

Location

From the VEE main menu at Excel [image] Close Workbook or Excel [image] Close All Workbooks.

See Also

To Save a Workbook to a New Name, Format, or Location or To Save a Workbook

Lab 8-1: Working with Workbooks


To Open a New Worksheet

Use the New Sheet menu option to create a new worksheet in the selected workbook.

Use

Create a text constant or a formula with the new name of the sheet enclosed (do not use * % $ # @ ! . in the name). Connect this to the input pin of the NewWorksheet UserObject. You can also send an empty string ("") to have Excel auto-name the sheet.

The new worksheet automatically becomes the active worksheet, and there is no need to do a select worksheet.

Notes

NewWorksheet only works with the active workbook.

Location

From the VEE main menu at Excel [image] New Sheet


To Select a Sheet

Use the Select Sheet menu option to choose a worksheet.

Use

Use a text constant or a formula on the input pin to provide a sheet name. This sheet becomes the active sheet in the open workbook.

Location

From the VEE main menu at Excel [image] Select Sheet


To Enumerate Microsoft Excel Workbooks, Worksheets, and Features

The main menu option Enumerations has four choices: Workbooks, Worksheets, Charts, and Names. It is used to create lists and counts of these items.

Use

The enumeration objects all have the same structure. They call a UserFunction that has two output pins. The upper pin is used to output the names of the open items into a one dimensional array. The lower output pin is used to provide the size of the array on the upper output pin.

Enumerations are quite useful during program development when you need to determine whether items are available. For example, determining whether a workbook can be selected and if a worksheet, chart, or named range exists.

Enumerations are also useful when you are using a non-English version of Microsoft Excel. Microsoft Excel uses different names for worksheets in different languages. By doing an Enumerate Worksheets, you can capture the name of the worksheet. See the example BarChart.vee in examples\ExcelLibrary\BarChart.vee and inspect the "Localize..." user object.

Location

From the VEE main menu at Excel [image] Enumerations [image] Enumerate Workbooks
From the VEE main menu at Excel [image] Enumerations [image] Enumerate Worksheets
From the VEE main menu at Excel [image] Enumerations [image] Enumerate Charts
From the VEE main menu at Excel [image] Enumerations [image] Enumerate Names

See Also:


To Format Text

The Format Text menu option is used to format text in a cell, a range, a named ranged, a row, or a column.

Use

The FormatText UserObject has an input pin that is used to capture the area to be formatted. You can provide a cell, row, column, named range, or range to the FormatText UserObject. A cell has the address format a9 (case insensitive), and a range would be a9:j22.

The FormatText UserObject contains a call to the UserFunction xlLib.FormatText and the Text Format Settings object. The Text Format Settings object is used to manage the appearance of the data in the cell. For example, the font, font characteristics such as bold, italics, and so forth, alignment, and some other miscellaneous features. See the open view parameters for more information.

See To Format Cells to format cell background parameters such as background color, grid lines, and number format.

Open View Parameters

The open view parameters for the Text Format Settings record object are:

  • FontName -- By default, the font is Courier New. You can set the font to any font that your system supports by just typing in the name of the font into the FontName field.

  • ForeColor -- By default, the fore color is black. You can set the fore color to any of 46 different colors.

  • Bold -- This can be either true or false. By default, it is True.

  • Italic -- This can either true or false. By default, it is False.

  • Underlined -- This can be either true or false. By default, it is False.

  • Size -- Point size ranges from 8 to 72 points. By default, it is 14 point.

  • HorizontalAlignment -- The possible alignments are left, center, right, justify, and general. The default is left. Numbers formatted with the General format are displayed just as you enter them. However, if the cell is not wide enough to show the entire number, the General format rounds numbers with decimals and uses scientific notation for large numbers.

  • VerticalAlignment -- The possible alignments are top, bottom, and center. The default is bottom.

  • WordWrap -- Wraps text values within the cell. The text does not "spill over" into the adjacent empty cell. Wordwrap only works with text values.

  • ShrinkToFit -- Reduces the text font size to fit the cell. This only works if WordWrap is off, and the cell is too small to fit the current value with the current font size.

Location

From the VEE main menu at Excel [image] Formatting [image] Format Text

See Also

To Format Cells and the example FormatTextAllColors.vee


To Format Cells

Use the Format Cells menu option to pass cell formatting requirements to Excel.

Use

The Format Cells UserObject passes cell formatting to Excel. You can define a single cell, a column, a row, a named range, or a range of cells to be formatted.

There is a single input pin where you provide a value for the cell or cells to be formatted.

Within the UserObject is a call to xlLib.FormatCells and an object named Cell Settings. Cell Settings contains all of the formatting options used to prepare the cell or cells.

See To Format Text to format cell foreground (Text) parameters such as foreground color, font, and alignment.

Open View Parameters

  • BackColor -- The background color for the cell. You can choose from 46 different colors. The default is SeaGreen.

  • NumberFormat -- The format applied to the numeric value. You choose from exponential notation, a mask (###.0) where values are optional, 0 where a digit or zero appears in the position, percentage, currency, general, or custom. Custom is the default number format. Numbers formatted with the General format are displayed the way you enter them. If the cell is not wide enough to show the entire number, the General format rounds numbers with decimals and uses scientific notation for large numbers. See Notes below for issues with non-English Microsoft Office.

  • CustomNumberFormat -- The custom number format you have defined for your use.

  • BorderEdges -- There are several ways to present the borders of the cell.

  • Grid -- Grid follows the Excel spreadsheet cell layout with top, bottom, and sides for each cell.

  • GridThickThin -- GridThickThin reformats a cell to a thin border even if the cell has a medium or thick border already in place.

  • Outline -- Outline follows the Excel spreadsheet cell layout with top, bottom, and sides for each cell.

  • LeftRight -- LeftRight sets borders on the left and right sides of the cell.

  • TopBottom -- TopBottom sets borders on the top and bottom sides of the cell.

  • Top -- Top sets a border on the top of the cell.

  • Bottom -- Bottom sets a border on the bottom of the cell.

  • Right -- Right sets a border on the right side of the cell.

  • Left -- Left sets a border on the left side of the cell.

  • BorderThickness -- There are three border thicknesses: Thin, Medium, and Thick. Thin has a darker cell border than if you choose Print Grid Lines through the Page Setup menu of Excel.

  • Pattern -- The Pattern describes the background of the cell, which can be displayed in several different ways.

  • Solid -- Solid is a solid background for the cell.

  • LightDots -- LightDots is a background that is dotted and the dots are the same size as the thin border.

  • MediumDots -- MediumDots is a background that is dotted but the dots are the same size as the medium border. The density of the dots is higher than the LightDots selection.

  • Checkered -- Checkered is a background that is checkered for the cell. These are intersecting parallel lines that are diagonal to the cell borders.

  • Grid -- Grid is a background that is also checkered for the cell. These are intersecting parallel lines that are parallel to the horizontal and vertical borders of the cell.

  • VerticalBars -- VerticalBars is a background that has vertical bars in the cell that are parallel to the sides of the cell.

  • HorizontalBars -- HorizontalBars is a background that has horizontal bars in the cell that are parallel to the top and bottom of the cell.

  • CrissCross -- CrissCross is a background that has small connected x's. The look is very similar to the Checkered option, but the density of the x's is heavier.

Notes

NumberFormat may not work in some non-English versions of Microsoft Office. Specifically, Russian Office 2003 does not accept any NumberFormat value except "General". Since many other non-English versions of Office work correctly, such as Japanese, German, Spanish, and Swedish, this appears to be a problem specific to Microsoft Russian Excel. A workaround is to set the NumberFormat yourself in a Formula. For example 'aRange.NumberFormat = "0,00"', using your localized thousands and decimal separators.

Location

From the VEE main menu at Excel [image] Formatting [image] Format Cells

See Also

See example FormatCellsAllColors.vee

Lab 8-3: Formatting Cells


To Auto Fit Columns

Use Auto Fit Columns to adjust the column width for numeric values or short text descriptions. The input pin can accept a cell, a range of cells, or a named range. This is designed for short text values and not lengthy descriptions.

Location

From the VEE main menu at Excel [image] Formatting [image] Auto Fit Columns


To Move to a Relative Cell Address

Moves from the active cell address to an address that is relative to the starting point.

Use

Cell Relative has three input pins. The top pin is the active cell address. The middle pin is for the distance you want to move the cell pointer left or right. The bottom pin is for the distance you want to move the cell pointer up or down.

By default, positive numbers move the cell pointer right and down. To move the cell pointer up or to the left, use negative numbers.

Location

From the VEE main menu at Excel [image] Navigation [image] Cell Relative

See Also

To Move to an Absolute Cell Address


To Move to an Absolute Cell Address

The CellAbsolute object moves the active cell address to a specific location on the spreadsheet. This location is not relative to any other location but is named directly in the CellAbsolute object.

Use

CellAbsolute has two input pins. The upper pin coincides with the columns in the spreadsheet, and the lower pin coincides with the rows in the spreadsheet. Both pins expect a numeric value.

There is one output pin. This pin can be used with an AlphaNumeric object or to push data to an input pin such as the address pin of the DataToCells object.

Location

From the VEE main menu at Excel [image] Navigation [image] Cell Absolute

See Also

To Move to a Relative Cell Address


To Find the First Empty Row

The FindFirstEmptyRow object finds the first empty row in the range you provide.

Use

There is one input pin. This pin is used to define the range to search for empty rows. For example, "A1:H60" will search rows 1 through 60 for the first empty row.

If an empty row exists within the range that you specify, the number of the row is returned. Otherwise, the FindFirstEmptyRow object returns a -1.

You can also use a named range, which you have defined in the Excel spreadsheet, as the input parameter. This is only supported in VEE Execution Mode 6 or higher.

Location

From the VEE main menu at Excel [image] Navigation [image] Find First Empty Row

See Also

To Find the First Empty Column


To Find the First Empty Column

The FindFirstEmptyColumn object finds the first empty column in the range you provide.

Use

There is one input pin. This pin is used to define the range to search for empty columns. For example, "A1:H60" will search columns A through H for the first empty column.

If an empty column exists within the range that you specify, the number of the column is returned. Otherwise, the FindFirstEmptyColumn object returns a -1. Use Excel [image] Navigation [image] Alpha Column from Numeric Column to convert the numeric column address returned by FindFirstEmptyColumn to create a valid row/column address.

You can also use a named range, which you have defined in the Excel spreadsheet, as the input parameter. This is only supported in VEE Execution Mode 6 or higher.

Location

From the VEE main menu at Excel [image] Navigation [image] Find First Empty Column

See Also

To Find the First Empty Row, To Convert from a Numeric Column to an Alphabetic One


To Alpha Column from Numeric One

Alpha Column from Numeric One

Given a column number input, converts it to the corresponding alphabetic Excel column reference.

Location

From the VEE main menu at Excel [image] Navigation [image] Alpha Column from Numeric Column

See Also

To Numeric Row and Column from Cell


To Numeric Row and Column from Cell

Returns numeric values for the row and column that correspond to the Excel style cell address input. If a range is input, only the upper left cell is used.

Location

From the VEE main menu at Excel [image] Navigation [image] Numeric Row and Column from Cell

.


To Send Data Settings

Send Data Settings controls the orientation of arrays and the handling of multi-dimensional arrays for the DataToCells call.

Open View Parameters

This UserObject consists of the call to the xlLib.SendDataSettings UserFunction and the SendDataSettings object. The SendDataSettings object has three parameters.

  • Orientation -- This is the direction in which the data flows for arrays. There are two options, Vertical and Horizontal. For example, a horizontal direction for a one dimensional array would create a row of data or a vertical direction for a two dimensional array would create two columns of data. The default is Vertical.

  • ThreeDArrays -- This controls how the Excel Library and DataToCells handle three dimensional arrays.

  • CreateNewSheets -- Creates new worksheets for the three dimensional array where each of the Z dimensions is a new worksheet. Each worksheet contains one of the two dimensional arrays.

  • CopyStartingSheet -- Copies the starting worksheet formats and applies them to the newly created worksheets from the three dimensional array process. This includes cell formatting, charts, and so forth.

  • UseSingleSheet -- Places all of the three dimensional data on a single sheet with each two dimensional array separated by a blank row.

  • ZLabel -- Used to label each two dimensional array that is presented as part of a three dimensional array.

Notes

For all three dimensional settings, each time a two dimensional array is printed, it is preceded by a row containing the value of the current element in the third dimension.

Location

From the VEE main menu at Excel [image] Send Data [image] Send Data Settings

See Also

To Send Data to Cells


To Send Data to Cells

Data to Cells is used to transfer data from VEE to Excel.

Use

Transferred data can be scalar or up to three dimensional arrays. The following data types cannot be transferred: Complex, PComplex, Spectrum, Coordinate, Waveform, Object, and Record. Use Send Data [image] Record to Named Ranges to send records to Excel. While the data types noted above are not directly supported by the DataToCells UserObject, there are examples that offer a work around for all of them. See the \Program Files\Agilent\VEE Pro 8.0\Examples\ExcelLibrary\SendingData directory.

DataToCells has two input pins. The upper pin accepts the data to be transferred. The lower pin accepts the cell address. While you can specify a range or named range, these are ignored, and the upper left corner of the address is used to determine the placement of the data in the worksheet. For example, a range of C4:K22 has the data display begin in C4, while the ending range address of K22 is ignored.

Because the ending address of the range is ignored, the DataToCells object is not bounds sensitive. If you send an array of ten elements into an Excel range of B4:B8, DataToCells writes over the next five values after B8. Remember, in a range, only the first value is important. The second value is not an effective boundary.

The DataToCells function places an array horizontally or vertically based upon the SendDataSettings object. Since the cell range is ignored and only the first value of the range is used, specifying "A1:A11" or "A1:J1" will do nothing to change the row or column orientation of the data. Use the SendDataSettings object to accomplish this.

There are also examples of working with two and three dimensional arrays in the Examples\ExcelLibrary\SendingData directory.

Location

From the VEE main menu at Excel [image] Send Data [image] Data to Cells

See Also

To Send Data Settings and To Send a Record to a Named Range


To Send a Record to a Named Range

Sends a VEE record to a named range in Microsoft Excel.

Use

The Call SendRecord UserFunction has an input pin and two output pins.

The input pin is used to send VEE records into the Call SendRecord UserFunction. The UserFunction then places the field values into correspondingly named ranges of the VEE Excel Library selected workbook. For example, if the VEE field name was called reading, the field value would be placed in an Microsoft Excel worksheet cell called reading.

To create a Microsoft Excel named range, highlight the group of cells you want to use and then go to Insert [image] Name [image] Define. Type in the name of the range and choose Add. You can also use the icon in the lower right corner ( [image]) of the Define Range dialog to toggle between a designate cells and define range dialog.

The two output pins are used to track the missing names and count how many are missing. Missing Names is populated when there are names defined in the Microsoft Excel worksheet that do not match a VEE field. So, if the VEE record is incomplete or the Microsoft Excel worksheet is improperly defined, there will be values on this pin. The second pin, Size, merely provides a count of the number of Missing Names.

Location

From the VEE main menu at Excel [image] Send Data [image] Record to Named Ranges

See Also

To Send Data to Cells and To Send Data Settings

Lab 8-4: Using Send Record


To Create a Line Chart

Creates a line chart in Microsoft Excel based upon the data that is fed from VEE.

Fields

CreateLineChart is a UserObject consisting of a function call to xlLib.CreateLineChart(Data,Settings) and a record object, Line Chart Settings. Line Chart Settings has many different fields, which are listed below.

  • Title -- The title for the graph. The title appears centered within the chart boundaries.

  • TitleFont -- The font used for the title. Any font supported by VEE is available for use here. Just enter the name of the font as it appears in the VEE font listing.

  • TitleFontSize -- You can choose from the sizes offered in the menu or select Autosize, which lets Excel choose a size automatically.

  • Type -- The type of chart.

  • Line -- A standard line chart.

  • Line with Markers -- A line chart with markers at each data point.

  • 3D Line -- Presents a three dimensional line chart.

  • Logarithmic -- Provides a logarithmic view of the data with markers at each data point. Be sure there are no zero or negative values in your data or the Excel Library will produce a 553 error. See Notes below for issues with non-English Microsoft Office.

  • NumericMarkers -- Places the data point value beside the data point.

  • FillEffects -- Affects the background of the graph. A value of None provides a grey background, while a value of Two Color provides a blended blue/white background. Logarithmic and three dimensional line charts are not affected by this parameter.

  • Names -- Each name in the list of names is applied to an array of values in your chart. For example, if you had an array of sine values, an array of cosine values, and an array of square wave values, you could label these in a legend by using the names parameter. Add more values to the list of names if you have more than 10 arrays.

  • XaxisLabel -- Enter the label for the X-axis values in your chart. For spectrum and waveform, enter no values and the VEE Excel Library creates a composite X-axis label with time span/frequency information.

  • YaxisLabel -- Enter any description you like for the Y-axis.

  • ChartSheet -- Enter the name of an existing sheet where you want the chart to appear. See Note below regarding localizing this string for non-English Microsoft Office.

  • DataCell -- The cell where the data block begins.

  • DataSheet -- Enter the name of an existing sheet where you want the data to appear. See Note below regarding localizing this string for non-English Microsoft Office.

  • PlotBy -- You can choose Columns or Rows. This determines whether the chart is created based upon data in the columns or the rows. You can also set this from the VEE main menu at Excel [image] Send Data [image] Send Data Settings.

  • Width -- Scale the width of the chart from standard size.

  • Height -- Scale the height of the chart from standard size.

  • MoveRight -- Microsoft Excel always places the chart in the same location on the worksheet. You can move the sheet to the right using this parameter. Negative numbers move the chart to the left. The movement increment is pixels.

  • MoveDown -- Microsoft Excel always places the chart in the same location on the worksheet. You can move the sheet down using this parameter. Negative numbers move the chart upwards. The movement increment is pixels.

Notes

Line Chart settings ignores the ChartSheet setting and always places the chart on the first or leftmost sheet. There is no work around.

The ChartSheet and DataSheet values are set to "Sheet1" by default. This does not work in many non-English versions of Microsoft Office. For example, in the German version of Microsoft Excel, the default value is "Tabelle1". If you prefer to change the sheet names, change these two values. If you want to use the default names, there is an easy way to these values localized.

Disconnect the lines between the LineChartSettings object and the "Call xlLib.CreateLineChart" object and connect a line from the output of the bottom-left "Localize..." object to the input of the "Call xlLib.CreateLineChart" object. This will modify the ChartSettingsRecord values for the fields ChartSheet and DataSheet to a value that is correct for the first existing worksheet for any version of Microsoft Office Excel.

Chart Type "Logarithmic" will not work in many non-English versions of Microsoft Office. To make it work, first, open Excel, do Insert [image] Chart and, in the Chart Wizard dialog, go to the second tab, "Custom Types". Note the spelling of the custom type for Logarithmic. For example, in German Office this is "Logarithmisch".

Next, go to the Create Line Chart object and open it. Near the top left you will see a formula with some instructions and a line similar to:xlApp.ActiveChart.ApplyCustomType(xlBuiltIn, "Logarithmic"); Follow the instructions for this formula.

Excel only accepts this Chart Custom Type string value as localized in the version of Microsoft Office. Yet Excel does not provide these localized names. Thus there is no way for the Excel Library to do this for you.

Location

From the VEE main menu at Excel [image] Create Chart [image] Create Line Chart

See Also

To Create a Bar Chart, To Create a Pie Chart, To Create an XY Chart, Releasing ActiveX References


To Create an XY Chart

Creates an XY chart in Microsoft Excel based upon the data that is fed from VEE.

Fields

CreateXYChart is a UserObject consisting of a function call to xlLib.CreateXYChart(Data,Settings) and a record object, XY Chart Settings. XY Chart Settings has many different fields, which are listed below.

  • Title -- The title for the graph. The title appears centered within the chart boundaries.

  • TitleFont -- The font used for the title. Any font supported by VEE is available for use here. Just enter the name of the font as it appears in the VEE font listing.

  • TitleFontSize -- You can choose from the sizes offered in the menu or select Autosize, which lets Microsoft Excel choose a size automatically.

  • Type -- The type of chart.

  • XYScatter -- A standard XY chart.

  • XYScatterLines -- An XY chart with lines connecting each data point. Data points have markers.

  • XYScatterLinesNoMarkers -- An XY chart with lines connecting each data point. Data points do not have markers.

  • XYScatterSmooth -- An XY chart with smoothed lines between data points. Data points have markers.

  • XYScatterSmoothNoMarkers -- An XY chart with smoothed lines between data points. Data points do not have markers.

  • XGridLines -- There are two choices, Major and Minor. Major means only a few grid lines, if any. Minor means many lines.

  • YGridLines -- There are two choices, Major and Minor. Major means only a few grid lines, if any. Minor means many lines.

  • Names -- Each name in the list of names is applied to an array of values in your chart. For example, if you had an array of sine values, an array of cosine values, and an array of square wave values, you could label these in a legend by using the names parameter. Add more values to the list of names if you have more than 10 arrays.

  • Scale -- Scale is either Linear or Logarithmic. Linear is straightforward. With Logarithmic, it applies only to the Y-axis. Zero or negative values cause an error.

  • FillEffects -- Affect the background of the graph. A value of None provides a grey background, while a value of Two Color provides a blended blue/white background. Logarithmic and three dimensional line charts are not affected by this parameter.

  • XaxisLabel -- Enter the label for the X-axis values in your chart.

  • YaxisLabel -- Enter any description you like for the Y-axis.

  • ChartSheet -- Enter the name of an existing sheet where you want the chart to appear. See Note below regarding localizing this string for non-English Microsoft Office.

  • DataCell -- The cell where the data block begins.

  • DataSheet -- Enter the name of an existing sheet where you want the data to appear. See Note below regarding localizing this string for non-English Microsoft Office.

  • PlotBy -- You can choose Columns or Rows. This determines whether the chart is created based upon data in the columns or the rows. You can also set this from the VEE main menu at Excel [image] Send Data [image] Send Data Settings.

  • Width -- Scale the width of the chart from standard size.

  • Height -- Scale the height of the chart from standard size.

  • MoveRight -- Microsoft Excel always places the chart in the same location on the worksheet. You can move the sheet to the right using this parameter. Negative numbers move the chart to the left. The movement increment is pixels.

  • MoveDown -- Microsoft Excel always places the chart in the same location on the worksheet. You can move the sheet down using this parameter. Negative numbers move the chart upwards. The movement increment is pixels.

Notes

The ChartSheet and DataSheet values are set to "Sheet1" by default. This does not work in many non-English versions of Microsoft Office. For example, in the German version of Microsoft Excel, the default value is "Tabelle1". If you prefer to change the sheet names, change these two values. If you want to use the default names, there is an easy way to these values localized.

Disconnect the lines between the "XY Chart Settings" object and the "Call xlLib.CreateXYChart" object and connect a line from the output of the bottom-left "Localize..." object to the input of the "Call xlLib.CreateXYChart" object. This will modify the ChartSettingsRecord values for the fields ChartSheet and DataSheet to a value that is correct for the first existing worksheet for any version of Microsoft Office Excel.

Location

From the main menu at Excel [image] Create Chart [image] Create XY Chart

See Also

To Create a Bar Chart, To Create a Line Chart, To Create a Pie Chart


To Create a Bar Chart

Creates a Bar chart in Microsoft Excel based upon the data that is fed from VEE.

Fields

CreateBarChart is a UserObject consisting of a function call to xlLib.CreateBarChart(Data,Settings) and a record object, Bar Chart Settings. Bar Chart Settings has many different fields, which are listed below.

  • Title -- The title for the graph. The title appears centered within the chart boundaries.

  • TitleFont -- The font used for the title. Any font supported by VEE is available for use here. Just enter the name of the font as it appears in the VEE font listing.

  • TitleFontSize -- You can choose from the sizes offered in the menu or select Autosize, which lets Excel choose a size automatically.

  • Type -- The type of chart.

  • ColumnClustered -- Vertical bars displayed adjacent to each other if PlotBy is rows and the data values are from the same row. If PlotBy is columns, then the elements in the array are displayed as adjacent vertical bars.

  • ColumnStacked -- Horizontal bars displayed adjacent to each other if PlotBy is rows and the data values are from the same row. If PlotBy is columns, then each array element is displayed as a vertical column with a color band for each element.

  • Stacked100 -- Displays the array elements in single vertical bars when PlotBy is rows. The array elements are added together, and each array element is presented as its percentage of the total. If PlotBy is columns, the arrays are displayed as vertical columns with a color band for each element.

  • 3DColumn -- Three dimensional vertical bars with the first array elements in the front and subsequent array elements displayed behind when PlotBy is rows. When PlotBy is columns, each array element has its own row of columns.

  • 3DColumnClustered -- If PlotBy is rows and the elements are from the same row, three dimensional vertical bars are displayed adjacent to each other. The front row of this display is the array elements. If PlotBy is columns, each array is presented as a cluster of columns with an array element equaling a column.

  • 3DColumnStacked -- Three dimensional horizontal bars displayed adjacent to each other if PlotBy is rows and the data values are from the same row. If PlotBy is columns, there is a column for each array and a color band for each array element.

  • 3DStacked100 -- When PlotBy is rows, displays the data in three dimensional single vertical bars. The elements are added together, and each element is presented as its percentage of the total. If PlotBy is columns, there is a column for each array and a color band for each array element.

  • BarClustered -- Horizontal bars displayed adjacent to each other if PlotBy is rows and the data values are from the same row. If PlotBy is columns, there is a horizontal bar for each element in the array and the bars are clustered.

  • BarStacked -- Horizontal bars displayed stacked on top of each other if PlotBy is rows and the data values are from the same row. If PlotBy is columns, there is a horizontal bar for each array with color bands for each array element.

  • BarStacked100 -- Displays the data in single horizontal bars when PlotBy is rows. The array elements are added together, and each array element is presented as its percentage of the total data point element. The appearance is the same if PlotBy is columns.,

  • 3DBarClustered -- Three dimensional horizontal bars displayed adjacent to each other if PlotBy is rows and the data values are from the same row. If PlotBy is columns, each array element is represented by a single horizontal bar, and the arrays are clustered.

  • 3DBarStacked -- Three dimensional horizontal bars displayed stacked on top of each other if PlotBy is rows or columns and the elements are from the same row. If PlotBy is columns, each array is represented by a single horizontal bar, and the array elements are banded and stacked.

  • 3DStacked100 -- Displays the data in three dimensional single horizontal bars when PlotBy is rows. The array elements are added together, and each element is presented as its percentage of the total. If PlotBy is columns, each array is represented by a single horizontal bar, and the array elements are banded and stacked.

  • Numeric Markers -- This places the element value beside the marker in the chart.

  • FillEffects -- Affects the background of the graph. A value of None provides a grey background, while a value of Two Color provides a blended blue/white background. Logarithmic and three dimensional line charts are not affected by this parameter.

  • XaxisLabel -- Enter the label for the X-axis values in your chart.

  • YaxisLabel -- Enter the label for the Y-axis values in your chart.

  • ChartSheet -- Enter the name of an existing sheet where you want the chart to appear. See Note below regarding localizing this string for non-English Microsoft Office.

  • DataCell -- The cell where the data block begins.

  • DataSheet -- Enter the name of an existing sheet where you want the data to appear. See Note below regarding localizing this string for non-English Microsoft Office.

  • PlotBy -- You can choose Columns or Rows. This determines whether the chart is created based upon data in the columns or the rows. You can also set this from the VEE main men Excel [image] Send Data [image] Send Data Settings.

  • Width -- Scale the width of the chart from standard size.

  • Height -- Scale the height of the chart from standard size.

  • MoveRight -- Microsoft Excel always places the chart in the same location on the worksheet. You can move the sheet to the right using this parameter. Negative numbers move the chart to the left. The movement increment is pixels.

  • MoveDown -- Microsoft Excel always places the chart in the same location on the worksheet. You can move the sheet down using this parameter. Negative numbers move the chart upwards. The movement increment is pixels.

Notes

The ChartSheet and DataSheet values are set to "Sheet1" by default. This does not work in many non-English versions of Microsoft Office. For example, in the German version of Microsoft Excel, the default value is "Tabelle1". If you prefer to change the sheet names, change these two values. If you want to use the default names, there is an easy way to these values localized.

Disconnect the lines between the "Bar Chart Settings" object and the "Call xlLib.CreateBarChart" object and connect a line from the output of the bottom-left "Localize..." object to the input of the "Call xlLib.CreateBarChart" object. This will modify the ChartSettingsRecord values for the fields ChartSheet and DataSheet to a value that is correct for the first existing worksheet for any version of Microsoft Office Excel.

Location

From the VEE main menu at Excel [image] Create Chart [image] Create Bar Chart

See Also

To Create a Line Chart, To Create a Pie Chart, To Create an XY Chart


To Create a Pie Chart

Creates a pie chart in Microsoft Excel based upon the data that is fed from VEE.

Fields

CreatePieChart is a UserObject consisting of a function call to xlLib.CreatePieChart(Data,Settings) and a record object, Pie Chart Settings. Pie Chart Settings has many different fields, which are listed below.

  • Title -- The title for the graph. The title appears centered within the chart boundaries.

  • TitleFont -- The font used for the title. Any font supported by VEE is available for use here. Just enter the name of the font as it appears in the VEE font listing.

  • TitleFontSize -- You can choose from the sizes offered in the menu or select Autosize, which lets Microsoft Excel choose a size automatically.

  • Type -- The type of chart.

  • Pie -- A standard Pie chart with no frills.

  • Pie Exploded -- A Pie chart with each segment of the pie 'exploded' out from the center, so they can be viewed separately.

  • 3DPie -- A three dimensional Pie chart with no frills.

  • 3DPieExploded -- A three dimensional Pie chart with each segment of the pie 'exploded' from the center, so they can be viewed separately.

  • PieOfPie -- A Pie chart of a pie chart. Usually the largest segment of the initial pie chart is then segmented into a second pie chart.

  • NumericMarkers -- Markers at each data point that help explain the underlying value.

  • None -- No markers are present

  • Label - Each array element is used to mark a segment of the pie.

  • Value -- Each pie segment is labeled with the value that produced it.

  • Percent - Each pie segment is labeled as a percentage of the whole.

  • LabelAndPercent - Each array element and its percentage is used to mark a segment of the pie.

  • NumericMarkersMore

  • LegendKey - Places a descriptive label beside each element of the pie.

  • LeaderLines - When the labels for each pie element become too crowded, leader lines can be selected. Leader lines are lines that connect the pie element with the descriptive label.

  • LegendKeyAndLeaderLines - Automatically shows the descriptive labels with leader lines.

  • None - No legend information is offered.

  • FillEffects -- Affects the background of the graph. A value of None provides a grey background, while a value of Two Color provides a blended blue/white background. Logarithmic and three dimensional line charts are not affected by this parameter.

  • ChartSheet -- Enter the name of an existing sheet where you want the chart to appear. See Note below regarding localizing this string for non-English Microsoft Office.

  • DataCell -- The cell where the data block begins.

  • DataSheet -- Enter the name of an existing sheet where you want the data to appear. See Note below regarding localizing this string for non-English Microsoft Office.

  • PlotBy -- You can choose Columns or Rows. This determines whether the chart is created based upon data in the columns or the rows. You can also set this from the VEE main menu Excel [image] Send Data [image] Send Data Settings.

  • Width -- Scale the width of the chart from standard size.

  • Height -- Scale the height of the chart from standard size.

  • MoveRight -- Microsoft Excel always places the chart in the same location on the worksheet. You can move the sheet to the right using this parameter. Negative numbers move the chart to the left. The movement increment is pixels.

  • MoveDown -- Microsoft Excel always places the chart in the same location on the worksheet. You can move the sheet down using this parameter. Negative numbers move the chart upwards. The movement increment is pixels.

Notes

The ChartSheet and DataSheet values are set to "Sheet1" by default. This does not work in many non-English versions of Microsoft Office. For example, in the German version of Microsoft Excel, the default value is "Tabelle1". If you prefer to change the sheet names, change these two values. If you want to use the default names, there is an easy way to these values localized.

Disconnect the lines between the "Pie Chart Settings" object and the "Call xlLib.CreatePieChart" object and connect a line from the output of the bottom-left "Localize..." object to the input of the "Call xlLib.CreatePieChart" object. This will modify the ChartSettingsRecord values for the fields ChartSheet and DataSheet to a value that is correct for the first existing worksheet for any version of Microsoft Office Excel.

Location

From the VEE main menu at Excel [image] Create Chart [image] Create Pie Chart

See Also

To Create a Bar Chart, To Create a Line Chart, To Create an XY Chart


To Send a Panel Image to a Picture

Exports a VEE graphic to Microsoft Excel.

Use

Panel Image to Picture is a UserFunction with four input pins.

  • userFunctionName a graphic image is created from this UserFunction and sent to Microsoft Excel as an image.

  • upperLeftCell is the starting point for the graphic in the Microsoft Excel worksheet.

  • relativeSizeX and relativeSizeY are ways to affect the height and width of the graphic. A value of one on these two pins leaves the graphic at 100% of its original size. Values less than one shrink the graphic and values greater than one increase its size.

Note

This UserFunction calls the VEE built-in function SavePanelImage(). BMP files can be heavily pixilated. It is recommended that you use .jpg graphics.

Location

From the VEE main menu at Excel [image] Send Panel Image [image] Panel Image to Picture

See Also

To Panel Image Settings

Lab 8-5: Creating an Excel Picture from a Panel Image


To Panel Image Settings

Establishes the number of colors and the file type for the send to panel function.

Use

The Image Settings object has two parameters.

NumberColors - This is 256 by default, which is the highest number of colors VEE supports.

FileSpecifier - This is the temporary file used for the transfer of the graphic to Excel. Specify the absolute path to the file. Be sure to provide a file name with an extension. The extension determines the file format. Leave this blank for the Excel Library to use a .jpg format.

Location

From the VEE main menu at Excel [image] Send Panel Image [image] Image Settings

See Also

To Send a Panel Image to a Picture


To Import Data from Cells

Imports data from an Excel spreadsheet into VEE.

Use

Get Data has two pins. The input pin accepts a cell, a range of cells, or a named range and is used to identify the cells to be imported from Excel. The output pin receives the imported data. For example, an alphanumeric object attached to this pin shows the values that have been imported.

If the cell contains a constant, this value is returned. If the cell is empty, an empty string is returned. If the cell contains a formula, the formula is returned as a string; in the same format in which you would see it displayed in the formula bar (including the equal sign).

Note that the behavior of getting data from an ActiveX server is different in VEE Execution Mode 5 versus Execution Mode 6. Specifically, the data type conversion when getting arrays of data was improved in Execution Mode 6. Calling DataFromCells in Execution Mode 5 versus Execution Mode 6 may yield different results. See the Enhancements Section of What’s New in Agilent VEE 6.0. The topic is Variant to VEE Data type Conversion - Improved Array Handling

note

Get Data cannot handle cells containing strings longer than 1024 characters due to a limitation of Microsoft Excel Object Library.

If you do need to get data from such a cell, use “xlApp.Range(Cell).Value” in a Formula as a workaround.

Location

From the VEE main menu at Excel [image] Get Data [image] Data from Cells


To Evaluate a Cell Formula

Gives the result of a cell formula.

Use

Provide a single cell address. Evaluate Cell Formula then returns the result of the formula in that cell.

Location

From the VEE main menu at Excel [image] Get Data [image] Evaluate Cell Formula


To Search an Array

VEE Excel Library includes a utility called Search Array. For one dimensional arrays, Search Array returns the index of the given Search Array value.

For two dimensional arrays, the Excel Library uses the value you provide as an index value and returns the corresponding [n,1] element. For example, a two dimensional array with values: [0,22], [1,24], [2,26]. A search array value of 2 would produce 24. 24 being the second element in the array.

Location

From the VEE main menu at Excel [image] Utilities [image] Search Array


To Use String Replace

Used to replace portions of a string with a different string portion. You can control whether the string replace is case sensitive or not.

Use

stringReplace does not require an open workbook. There are four input pins on the stringReplace UserObject.

  • string - The string that will be changed.
  • outSubString - The sub-string being removed.
  • inSubString - The sub-string replacing the outSubString.
  • caseSensitive - Use a 0 to ignore case. Use a 1 to force a case comparison between the inSubString and the outSubString. If they do not match, the substitution is not completed. To enhance performance, try to use Case Sensitive replace instead of Case Insensitive replace whenever possible.

Location

From the VEE main menu at Excel [image] Utilities [image] String Replace


To Establish Print Settings

Use this UserObject to prepare the printer for printing.

Open View Parameters

The PrintSettings UserObject consists of a call to the PrintSettings UserFunction and the Print Settings object. The Print Settings record object contains all of the open view parameters needed to configure the printer.

  • PrintCopies -- Set the number of copies you wanted printed with this field. You must print at least one copy.

  • ActivePrinter -- Enter a printer name. Leave it blank and either the default printer is used or the last printer used by Excel is targeted. For example, \\servername\printername.

  • PrintFromPage -- The print job starts from the page that is chosen here. This is 1 by default.

  • PrintToPage -- The print job ends at this page. This is 32767 by default.

Notes

Users with non-English versions of Office may notice issues with default paper size. Excel 2002 attempted to correct this by adding the property Application.MapPaperSize. In your VEE program using the Excel Library, this would be "xlApp.MapPaperSize". If this property is set to true, Excel 2002 and later versions attempt to automatically switch between the standard paper sizes of different countries. Agilent's testing showed that the MapPaperSize property defaults to true in Excel 2002 and 2003, but the default value is not documented.

Location

From the VEE main menu at Excel [image] Printing [image] Print Settings

See Also

To Print Workbooks and Worksheets, To Preview a Print Job, and Releasing ActiveX References


To Preview a Print Job

Retrieves the active worksheet into Excel's print preview screen.

Note

If you choose to print from the print preview screen and have a Print Worksheet object later in your program for the same worksheet, the worksheet will be printed twice.

Print Preview automatically makes Microsoft Excel visible.

Location

From the VEE main menu at Excel [image] Printing [image] Print Preview

See Also

To Print Workbooks or Worksheets and To Establish Print Settings


To Print Workbooks or Worksheets

Prints the active workbook or worksheet.

Use

The Print UserObject contains a Print record object and a call to the xlLib.Print UserFunction.

The Print object has a drop-down menu pick where you can select between worksheet or workbook.

Location

From the VEE main menu at Excel [image] Printing [image] Print Workbook or Worksheet

See Also

To Establish Print Settings and To Preview a Print Job


Excel Library FAQ

Q: Can I still use ActiveX Automation along with Excel Library?

A: Yes, you can access the Microsoft Excel application object to enhance your VEE application beyond features the VEE Excel Library provides. After initializing the VEE Excel Library, your program can use the global xlApp object, which is the Excel application, and go from there. For example, you can place xlApp.ActivePrinter in a formula object to retrieve the default printer's name. Note that you will have to change the name of any existing variable named 'xlApp' or make its scope local.

Q. Can I call UserFunctions in the VEE Excel Library directly?

A. This is not supported. They are not documented and the only supported interface to VEE Excel Library is through the VEE Excel Library menu selections.

Q: Sometimes when starting up, VEE uses the instance of Excel already launched, and sometimes it creates another instance. Why is that?

A: If an instance of Excel exists, VEE Excel Library tries to re-use it when starting up. If Excel was left in edit mode, where a cell is being edited and the user has not yet pressed enter, VEE Excel Library cannot communicate with that instance of Excel. Excel stops responding to ActiveX Automation in this case, so VEE Excel Library loads another instance of Excel. It is best to avoid using Excel interactively while running VEE Excel Library based VEE programs.

Q: Why is Excel invisible initially?

A: Excel is not set to be visible when xlLib.Initialize is called because, for most automated applications, no user interaction is required. A user can prevent VEE Excel Library from continuing if the user is in the middle of editing a cell and hasn't hit Enter yet. To make Excel visible, use the xlLib.Settings object and set visible to True.

Q: How do I create an error handler for trapping errors that occur inside VEE Excel Library?

A: Create UserFunctions to handle errors, as many as you want. Define a global text variable 'userErrorHandler' and set its value to the name of the error handler UserFunction you currently want to use. If 'userErrorHandler' is defined and callable, it precludes execution of VEE Excel Library's error handler for most raiseable errors inside VEE Excel Library.

Your error handler UserFunction must have two data inputs, which will be sent the ErrorMessage and ErrorNumber. Your error handler UserFunction cannot have any data outputs. You must also use a VEE Excel Library Settings object in your program (before generating an Excel error) and set the ErrorAction to RaiseError for your error handler function to be called.

Q: I am using a non-English version of Excel and VEE Excel Library is throwing errors when I create charts. What should I do?

A: Microsoft Excel names worksheets differently depending upon the language version you are using. VEE Excel Library defaults to the English version. There is a simple work around for this issue, see the BarChart.vee example program in examples\ExcelLibrary\BarChart.vee.

Q: I entered some text into a cell while Excel was under the control of the Excel Library. Now I have some random and strange errors.

A: Microsoft Excel does not accept input while being controlled remotely. Entering anything while Excel is under the control of the Excel Library will produce random, odd results.

See Also Releasing ActiveX References


Vxl Changes

Differences between Vxl and Excel Library

This file lists the issues for Vxl 2.0 users using their Vxl 2.0 programs in VEE 7.5 or later's Excel Library.

Changes that do not affect your current Vxl programs:

A. A copy of the Excel Library UserFunction library file, ExcelLibrary.vxe, is installed in the old Vxl 2.0 location ~installDir\lib\vxl\vxlLibrary.vxe. Vxl 2.0 programs will just work because they will find the new library in the old location. You are encouraged to upgrade your programs to use the new location, ~installDir\lib\ExcelLibrary\ExcelLibrary.exe

B. There are seven renamed functions noted in the table below, but the old function names have been retained as pass-through functions and marked on their panel as deprecated. This means Vxl 2.0 programs should work as-is, though these function names may go away in the future.

C. There is also one other pass-through function, Open, retained from Vxl 1.0 days. This should allow all Vxl 1.0 programs to work unchanged. Open in Vxl 1.0 was renamed to OpenRW in Vxl 2.0, and is now OpenWorkbookRW in Excel Library.

D. Some items on the menu have been renamed. For example, Data From Cells to Get Data and Initialize Vxl to Initialize Excel Library. The new names won't have any impact on your Vxl programs.

E. The .vee files that the menu uses to create the menu objects have been renamed, but this should not affect your programs. For example, Save.vee is now SaveWorkbook.vee. Unless you did #4 below, this should not matter.

F. Menu items have been moved around on the menu. For example, About Vxl at the bottom of the menu has been moved to the top (and is renamed What is this menu?).

G. The Vxl Samples were installed under ~installDir\examples\Vxl\ and are now installed under ~installDir\Examples\ExcelLibrary\

H. The names of the private UserFunctions in the UserFunction Library have been changed. These are the UserFunctions that are not called from any menu item, only called internally inside the library. Changes to these function names will not be documented. In fact, all of these private functions have been renamed to begin with zzInternal to make it more obvious that you should not call these directly.

I. No samples have been deleted, only the FourInARow.xls game, which was not a VEE program. All of the Samples have been renamed to remove the leading word Example, and several of the examples have been further renamed to make it clearer what they do.

Changes which might break a Vxl program:

1. Main menu, Initialize Vxl [image] Import Library [image] Library. vxl is renamed to xlLib. This is used in all of the calls to the library, for example the call to vxl.Initialize is now a call to xlLib.Initialize. If you only modify your program to account for the other breaking changes documented, this particular rename does not matter, and your program will work as-is in VEE 7.5. However, if you want to modify your program by adding in another object from the Excel menu, the new object will not work. You have to either modify every new object created from the Excel menu to use the old vxl name, or modify your program to use the new xlLib name.

2. The imported global named xl is renamed to xlApp. By default none of the menu entries used this directly, so it is unlikely your programs are affected. However, some of the Examples use it, and the Notepad entry for the main menu item Settings tells you how you can use it directly (eg. set xl.DisplayAlerts=False). If you used it, you would have to translate any usage to xlApp.DisplayAlerts=False.

3. If you customized your Vxl menu, you will have to re-do that work and start over with the VEE 7.5/8.0 Excel menu file. This is because of the changes above in (E).

4. If you call any private UserFunctions in the library, the rename noted in (H) above will break your program.

Table of Changes

Changes are highlighted in Yellow.

Vxl Menu Item Name | Excel Menu Item Name | Vxl UserFunction Name | VEE 7.5/8.0 Excel Library UserFunction Name | Comments
 | QuickStart / ShortCuts |  |  | New in 7.5
Initialize Vxl | Initialize Excel Library | Initialize | Initialize | See Breaking Change (1)
Open Workbook | Open Workbook | OpenRW | OpenWorkbookRW | Rename of UserFunction
Navigation -> Alpha Column From Numeric Column | Navigation -> Alpha Column From Numeric Column | vxlData2CellsAlpha ColFromNumericCol | AlphaColFrom NumericCol | Rename of UserFunction
Navigation -> Numeric Row and Column From Range | Navigation -> Numeric Row and Column From Range | vxlData2CellsNumeric RowColFromRange | NumericRowCol FromCell | Rename of UserFunction
Send Data -> Data To Cells | Send Data -> Data To Cells | Data2Cells | DataToCells | Rename of UserFunction
Send Panel Image -> Panel Image to Picture | Send Panel Image -> Panel Image to Picture | PanelImage2Picture | PanelImageToPicture | Rename of UserFunction
Data From Cells -> Evaluate Cell Formula | Get Data -> Evaluate Cell Formula | EvalScalar | EvalCellFormula | Rename of UserFunction
Quit Vxl | Quit Excel Library | QuitVxl | QuitExcelLibrary | Rename of UserFunction
Utilities -> Iterate Record | Utilities -> Iterate Record | <none> | <none> | New in 7.5

See Also

Releasing ActiveX References


Debugging Programs in Agilent VEE

VEE displays error messages during development and when a program runs, and can display caution, error, and informational messages as follows:

• When you run a program, VEE may display a yellow-titled Caution box.

• When you run a program, VEE may display a red-titled Error box.

• If you make a mistake while creating a program, such as typing an out of range value of 33000 into an Int16 Constant, VEE displays an Error message box with a dark blue title bar.

• VEE also displays information in the status bar about errors and cautions. The status bar is along the bottom of the VEE window.

See Also

To View Data Flow and Program Execution

To Control Breakpoints

To Step through a Program

To View the Call Stack

To View the Data on a Line

To Examine Terminals

To Track the flow of data using Alphanumeric

To Find the Endpoints of a Line

To Trap an Error

To Resolve Errors

To Locate an Error

To View the Last Error

To Follow the Order of Events Inside an Object

To Follow the Execution Order of Objects in a Program

To Find an Object in a Complex Program


To View Data Flow and Program Execution

You can view data flow and program execution flow in the Detail View of a VEE program while it is running. Data flow and program execution are visible in the Main Window, and in UserObject and UserFunction edit windows.

To view data and execution flow

1. Switch to the Detail View of the context(s) of interest.

2. Click the Show Data Flow and Show Execution Flow buttons on the toolbar.

Show Data Flow button

Show Execution Flow button

3. Run the program to see data and execution flow:

Data flow is indicated by small square markers moving along lines. These markers represent data containers. To change the speed that the markers move, see the next topic below.

Execution flow is shown by highlighting each object as it operates. The highlight is a light green outline around an object as it executes. The highlight changes to dark green after the object executes.

To change the data flow rate

1. Select Default Preferences from the File menu.

2. On the General tab, in the Debug group, click on the Data Flow Rate arrow to show the drop-down list. You can set a rate from 1 (slowest) to 10 (fastest).

3. To save the changes as new defaults VEE.RC, click on Save . Click on OK if you want to use the changes for this VEE session only (until you select File [image] New, Open, or Exit).

Tips

You can show data and execution flow independently by turning only one on at a time.

You can turn these features on and off whether the program is running or not.

Be sure to turn these debug features off when you don't need them. They slow down your program considerably.

The Show Data Flow and Show Execution Flow commands are in the Debug menu. Checkmarks beside the commands show that the features are on.

In VEE 4 and higher execution modes, the debugging features are disabled if the Disable Debug Features default preference is turned on.

See also

Default Preferences

To View the Call Stack


To Control Breakpoints

If you set a breakpoint on an object in your program, the program will pause just before that object operates. Then you can use Line Probe to see the data containers on each line, and you can Step or Resume program execution. Commands are available that let you toggle the breakpoint settings on objects you select, and control breakpoints for your entire program.

To toggle breakpoints

1. Select the objects where you want to change breakpoint settings. To select objects, press and hold the Ctrl key, then click on objects with the left mouse button.

2. Click the Toggle Breakpoint button on the toolbar (Debug [image] Toggle Breakpoint). The breakpoint settings on the objects you selected will be toggled. Breakpoints are cleared if they were previously set, and the objects’ highlighted outlines disappear. Breakpoints are set if they were previously clear, and the objects display highlighted outlines.

Toggle Breakpoint button

3. Run your program. The program pauses just before the object where a breakpoint is set.

4. To continue, click on one of the program-control buttons:

Resume button to resume execution.

Step Into button to step into a UserObject or UserFunction.

Step Over button to step over to the next object.

Step Out button to step out of a UserObject or UserFunction.

Stop button to stop the program.

To activate all breakpoints

1. Click on Debug [image] Activate Breakpoints.

A check mark by the menu command means all breakpoints that are set will be active when you run your program (default).

To clear all breakpoints

1. Click on Debug [image] Clear All Breakpoints.

All breakpoints in your program are cleared and the highlighted outlines disappear from the objects.

Shortcut

Press CTRL+B to toggle breakpoints.

Tips

You can also control an object's breakpoint using Properties from the object menu. On the Behavior category change BreakpointEnabled to True or False to set or clear the object's breakpoint.

In VEE 4 and higher execution modes, the debugging features are disabled if the Disable Debug Features default preference is turned on.

See also

To View the Call Stack

Default Preferences


To Step through a Program

Use the three Step buttons with the other program-control buttons on the toolbar to run your program one object at a time. The program-control buttons are:

Step Into button

Step Over button

Step Out button

Run/Resume button

Pause button

Stop button

Interactions of program-control buttons

From a stopped program, the first time you click a Step button, the program PreRuns. Click the Step Into button to operate each object in turn. The object highlighted with a yellow outline operates next.

Step Into button

If you run your program with a breakpoint enabled, the program will PreRun and then execute up to the breakpoint. From there, you can use the Step Into button to operate each object in turn.

Step Into button

At any point while stepping through a program, you can click the Resume button to continue running the program. To pause the program, click the Pause button. If you then stop the program, it will go through PreRun when restarted.

Resume button

Pause button

Stepping through a UserObject or UserFunction

The three types of Step buttons let you control how the program steps through another context in the program such as a UserObject or UserFunction:

Step Into steps into the context opening the edit window in its Detail View for you to step through the objects in it.

Step Over executes the entire context, stepping to the next object in the program.

Step Out leaves a context you are stepping through by executing all remaining objects in it, then stepping to the next object in the program.

Tip

In VEE 4 and higher execution modes, the debugging features are disabled if the Disable Debug Features default preference is turned on.

See also

To View the Call Stack

Default Preferences


To View the Call Stack

Use the Call Stack tool window (View [image] Call Stack) to view the next object to execute and the calling context(s) in a paused program. The Call Stack is most useful when kept open while stepping through a program or using breakpoints. You can open and close the Call Stack from the menu or with its toolbar button while the program is paused or stopped.

Call Stack button

The Call Stack tool window lists the current calls to UserObjects or UserFunctions including input variables. The following figure shows the Call Stack with sample data. The next object to execute is contained in the UserObject Gen Sine Waves, which is contained in the Main program. Gen Sine Waves has three inputs Freq1, Freq2, and Phase.

Interactions with Program Controls

When the Call Stack is open, it contains information only when a program is paused. No information is available when a program is running or stopped.

Each time a program pauses, the Call Stack automatically updates, remaining in sync with the program execution flow.

The Call Stack displays information when a program is paused by:

pressing the Pause button.

using the Step Into, Step Over, and Step Out buttons.

a breakpoint setting.

a program execution error.

Accessing Call Stack Contents

When a program is paused and the Call Stack is open, the current context is displayed and the next object to execute is highlighted.

To access any context in the current Call Stack list, double-click on the context name, and the program will display it.

See also

To View Data Flow and Program Execution

To Control Breakpoints

To Step through a Program


To View the Data on a Line

Use the Line Probe command (Debug [image] Line Probe) to view the data container that has been passed on any VEE data line. The program must be paused or stopped.

To probe a line quickly, simply move the mouse pointer over the desired line. The pointer changes shape and a line tip appears summarizing the data. Click on the line to see the Line Value box as shown in the following figure:

If you probe a line on which no data has been transmitted (or on which a sequence pin "ping" has been transmitted), the Line Value dialog box reports Nil (empty) container.


Examining Terminals

To Examine Terminals

To examine a terminal, double-click it in the open view . If an object is iconized, place the mouse pointer over the terminal, and VEE automatically pops up the name of the terminal.


Using the Alphanumeric Displays for Debugging

To Use the Alphanumeric Displays for Debugging

You can add the Alphanumeric or Logging Alphanumeric displays at different points in a program to track the flow of data. When the program is running correctly, delete them. AlphaNumeric displays a single data container (a Scalar value, an Array 1D, or Array 2D), and Logging AlphaNumeric (either a Scalar or Array 1D) displays consecutive input as a history of previous values. You can also use a Counter to see how many times an object ran.


To Find the Endpoints of a Line

Use the Line Probe command (Debug [image] Line Probe) to trace a line and show its endpoints. The program must be paused or stopped.

To probe a line quickly, simply move the mouse pointer over the desired line. The pointer changes shape and the line is highlighted with its endpoints. Click on the line to see the data container.


To Trap an Error

Normally, all VEE errors are reported by the Error Message dialog box. However, you can trap an error generated by a particular object by adding an Error output terminal to that object.

To add an Error output terminal to an object, select Add Terminal [image] Error Output from the object menu.

If an object that has an Error output terminal generates an error, the normal VEE Error Message dialog does not appear. Instead, the Error terminal outputs the error number that must be processed by the program.

There are various ways to use the Error output terminal:

Use the Error output to activate another object, such as Raise Error.

Use If/Then/Else to determine an action based on the error number.

Use errorInfo()to view error information for the last trapped error.

Example

Open the program manual37.vee in your manual examples directory (Help [image] Open Example...). It shows some techniques for trapping errors.

See also

errorInfo()

Error Output (Object Menu)

Raise Error


Resolving Errors

To Resolve Errors

If you get an error message when you run a program, VEE automatically puts a red outline around the object where the error was found.

You can either correct the error and the outline will disappear, or you can click the Stop button, which will remove the red outline, and then fix the error. If you click Stop, you can look at the error again before resuming, with View [image] Last Error.


Using the Go To Button to Locate an Error

To Use the Go To Button to Locate an Error

The following figure shows an example runtime error message. When this program runs, VEE displays a Run Time error and shows a red outline around the UserObject AddNoise. When the Go To button is pressed, VEE opens the UserObject AddNoise and shows a red outline around the A + B object, which is missing a connection on the A input pin. In a large program, the Go To feature can help you locate the source of an error quickly.


To View the Last Error

VEE errors are reported by the Error Message dialog box. When an error is reported, you may need to close the error dialog box in order to access the problem in the program. To view the error message again, click on View [image] Last Error.

Errors handled by an Error output terminal on an object cannot be viewed with this command.

The Last Error buffer is cleared when the program is run again or when a new program is loaded.


Following the Order of Events Inside an Object

To Follow the Order of Events Inside an Object

The following figure shows the order of events inside an object.

The pins operate as follows:

1 | If the sequence input pin is connected, the object will not operate until it receives a message to execute (a “ping” in VEE terms). However, the sequence input pin does not have to be connected.
2 | All data input pins must have data before the object operates. (You can add data input/output pins to most objects. Click on the Add/Delete Terminal menu in any object menu to find out the pins that can be added.)
3 | The object performs its task. In this case, A is added to B and the result is placed on the output pin.
4 | The data output pin fires. The object waits for a signal from the next object that the data is received before its operation is completed. Therefore, a given object does not fire its sequence output pin until all objects connected to its data output pin have received data.
5 | The sequence output pin fires.

There are exceptions to this sequence of events:

• You can add error output pins to trap errors inside an object. The error output pins override the standard object behavior. If an error occurs when the object executes, the error pin will send out a message and the data output pins will not fire.

• You can add control input pins to some objects, and they may cause the object to perform some immediate action. For example, an object sub-function such as Title or Autoscale in the Waveform (Time) display can be performed with control pins. Control lines to an object are shown in VEE programs as dashed lines

For example, the following figure shows a control line that sets a custom title for the waveform display. Note that the object is not required to have data on a control pin to perform this action. The object does not execute, only the action such as setting the title is performed. You can click Show Data Flow to see how the control line to the Title control input will carry data first.


Following the Execution Order of Objects in a Program

To Follow the Execution Order of Objects in a Program

As a VEE program runs, the objects execute in the following order:

1 Start objects operate first.

Following figure shows a VEE program with two threads, which are sets of objects connected by solid lines in a VEE program. The Start objects, located under Flow [image] Start, are used to operate the individual threads in a program. If a program includes Start object(s), they execute first.

2 Objects with no data input pins operate next. Data [image] Constant objects are often in this category.

3 Objects with input pins will only operate when all connected inputs are satisfied. (Recall that connecting sequence inputs is optional.)


To Find an Object in a Complex Program

To find a particular object, especially in a large program, select Edit [image] Find. Type in the object or function name in the pop-up dialog box, and VEE displays all instances and locations of that object or function in the program. (See “Finding Functions in Large Programs" for more details.)


To Add Structure to Your Program

The following tips show how you can add structure to a VEE program.

1. Analyze what your VEE program does. Can you identify a group of objects that together perform a specific sub-task? Create a UserObject from those objects.

2. Are there sub-tasks that appear multiple times in your program? If so, create a UserFunction to do the task, and call the UserFunction each time it is needed.

3. Proceed through your program, building a hierarchical structure using UserObjects and UserFunctions.

4. If you pass a single data container to several objects, consider using a global variable to pass that data.

See also

To Create a UserObject in a Program

To Create a UserFunction in a Program

UserObject

UserFunction


To Document Your Program

You can make your program easier to use, debug, and maintain by using the following techniques:

1. Give your program a descriptive name. When saving the program, use a file name that indicates its function. This name also appears at the top of the Program Explorer. If the Main Window has a panel view, use its Properties Window to enter a title for the associated Execution Window. This title replaces the file name in the Program Explorer, and appears in the Execution Window’s title bar when you run the program. These names are used with the program-documentation feature Save Documentation.

2. Rename objects to names that are more meaningful to you. For example, Repeat 100x may be more useful than For Count. (In the object’s Properties Window, change the entry for Title.)

3. Rename input and output terminals to descriptive names. For example, if terminal A inputs a flow rate, you may want to change the name to Flow_Rate. (Double-click on the terminal and change the title in the dialog box.) You cannot change the title of some terminals.

4. Add descriptions to key objects and functions by using Description in the object menu. The information may include why you used that particular object, details about the inputs and outputs, and the options that you used on the object. Use short descriptions to keep the program size smaller.

5. Add notes to yourself or others using the Note Pad display object (Display [image] Note Pad). The information could include:

Your name, and phone number, and the date you created the program.

What this program does.

The dates that you made changes and what the changes were.

6. Customize icons, such as UserObject icons, by adding a descriptive bitmap.

7. Use the print commands to make hardcopy printouts of your program. Print commands are on the File menu, the object menus of the Main Window and UserObject/UserFunction edit windows, and on the Program Explorer (click on names with the right mouse button).

See also

To Add a Bitmap to an Icon

To Add a Picture to the Panel

Description

Save Documentation


To Add a Bitmap to an Icon

You can add a bitmap to any iconified VEE object.

To add a standard bitmap

1. Select Properties from the object menu. In the Icon Appearance category, select IconPicture.

2. The available bitmaps in your bitmaps directory are displayed in the Picture group. Scroll through the list and click on the file name that you want. For example, if you click on beep.icn, the Beep icon is shown in the Preview area.

To browse through other directories, click on Browse. The Select File dialog box appears letting you navigate through the directories to select a bitmap file.

3. The following is a UserObject icon with the Beep bitmap:

To add a custom bitmap

The procedure for adding a custom bitmap is the same as for adding one of the standard bitmaps. However, you must first create the bitmap. To create a custom bitmap, use an appropriate bitmap editor for your computer (for example, the Microsoft Paint program). The following file formats are supported:

BMP, ICN, or GIF

The default bitmap directory is:

C:\Program Files\Agilent\VEE Pro 8.0\bitmaps

See also

To Add a Picture to the Panel


To Profile Execution Parameters

Use the Profiler (View [image] Profiler) to collect execution information about a program. The Profiler measures execution parameters regarding the amount of compiler time each context (Main, UserObject, or UserFunction) uses while a program runs. This information is useful when you want to modify your program to maximize efficiency, and improve execution speed. You can open and close the Profiler from the menu or with its toolbar button.

Profiler button

The data in the Profiler display shows the amount of compiler time each context uses to execute. The following figure is an example of a profile including the number of executions for each context with the percentage of time and number of seconds used in the elapsed program time:

To profile a program

1. Open a program.

2. Open the Profiler (View [image] Profiler or use the toolbar button).

If necessary, click Options button change how data is displayed and saved to a file.

3. Click the Start Profiling button on the Profiler. The status indicator PROF is highlighted on the VEE Window status bar. You can leave the Profiler open or close it; once you start the Profiler, it collects data whether it is open or not.

4. Run the program.

5. With the Profiler open, click the Refresh button to update the display.

You can refresh the display during any program state: running, paused, or stopped. New data is always collected while the Profiler is running, but you must refresh the display to see the new data. Data is retained until you click Clear, open another program, or click File [image] New.

To sort the displayed data by column, click a column label to resort the data in reverse order.

6. Click Save to write profile data to a file. You must click Refresh before clicking Save to include the latest data. The saved file includes a calculated total of %Time and Time(sec).

7. Click Stop Profiling to stop collecting data.

Tip

To bring the Main Window, a UserObject, or a UserFunction into view in the work space, double-click the context name in the Profiler display.

See also

Profiler


To Remove Barriers to Program Performance

The following are some general techniques that you may be able to use to improve program execution speed.

Use VEE’s VEE 4 or higher execution modes and disable the debug features on the Default Preferences dialog box. These modes run programs in a compiled execution mode.

On UserObjects and UserFunctions, choose a specific data type and shape required on the data input terminals; do not leave them set to Any. Specifying these parameters helps the program run faster in the VEE 4 and higher execution modes. For other objects, leave data type and shape set to Any. Then, VEE converts data types only when necessary, saving execution time. See Converting Data Types on Input Terminals.

Turn off Clear at PreRun and Clear at Activate on displays where not needed.

Use Initialize at PreRun and Initialize at Activate on data objects instead of setting defaults with control pins.

Collect data for graphical displays into an array, and plot the entire array at once rather than plotting each individual scalar point. If the X values of a plot are regularly spaced, use an XY Trace object rather than an X vs Y Plot object.

Run the program from the panel view. If the panel view contains fewer objects than the detail view, the program will run faster.

Set graphical displays to be as plain as possible. The settings that allow the fastest update times are Grid Type [image] None and all Layout features disabled. Use the Auto Scale control input only when needed, since it slows down a program.

Turn off unnecessary digital displays on indicators such as the Fill Bar, Meter, Tank, and Thermometer objects.

Iconify those objects that continuously update their displays (such as the Timer, Counter, Accumulator, AlphaNumeric, and graphical display objects) if you don't need to see the displayed information.

If using a Strip Chart display, set the buffer size as small as possible.

Collect data for processing into an array, and then process the data as an array.

Use Complex data in expressions rather than PComplex. Most of the math libraries will convert PComplex to Complex, calculate the answer, and convert Complex back to PComplex.

To display PComplex data, set Trig Mode (under File [image] Default Preferences) to Radians. VEE stores PComplex values internally as radians.

If importing libraries of functions (Device [image] Import Library), delete them after the program no longer needs them (Device [image] Delete Library).

For sections of a program requiring fast execution, create compiled functions using a textual programming language.

In general, the fewer objects that need to operate, the faster the program will run. Perform as many functions as possible in each object.

See also

To Reduce the Number of Objects in a Program


To Reduce the Number of Objects in a Program

Many VEE objects can perform a set of functions. Your programs will be more compact, easier to maintain, and will run faster if you use the following techniques:

Enter equations in a Formula object instead of connecting several constant and single-function math objects to input terminals on a Formula. You can nest functions in a Formula object. For example, you can enter the expression (sin(ramp(100, 0, 360))).

Use one If/Then/Else object with multiple conditions (for example, A == B OR A<=C AND A>D) instead of using multiple If/Then/Else or Conditional objects.

To input a one-dimensional array of data, use a Constant object configured as an array instead of using one Constant object for each value and then building an array.

To read all of "the rest" of the data in a file, use the ARRAY 1D TO END:(*) transaction in a From File object. This is simpler and faster than looping on single-element reads and collecting the result into an array.

Use the Sequencer to control the flow of execution of several UserFunctions.

When using the Sequencer, only enable logging for transactions where the Log record is required. If the Log output terminal is not used, delete it to speed up execution slightly.

See Also

Sequencer


To Increase I/O Performance

In general, direct I/O provides the fastest I/O performance. To optimize the I/O performance of your VEE program:

1. Create your program using an instrument panel object (or component driver object) to communicate with the instrument. Test and debug the program and instrument configuration.

2. Rewrite the program so that it uses a Direct I/O object to communicate with the instrument using the "captured" messages. This will speed up I/O performance in the final program. For a long string of instrument commands, consider storing them in a Text object connected to a Direct I/O object’s data input.

3. In cases where extremely fast I/O is required, you can create a compiled function to perform the instrument I/O function.

See also

Agilent IO Monitor

Direct I/O

To Use a Direct I/O Object

Using a Compiled Function


To Change Properties Programmatically

To Set and Get Properties Programmatically

You can get and set properties of VEE Objects at runtime without affecting the design-time value of that property.

To programmatically get/set properties

Go to the Properties window of a VEE object. Under the Design category, fill in the Declared Name field. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. After setting the Declared Name, you can GET/SET properties of that VEE Object. For example, you can change its BackColor, size, location, title, and etc. The following table shows objects and their properties that can be SET/GET programmatically.

Property | Object
BackColor, ForeColor, Title, Size, Location, and Visibility | All VEE objects
Value | Toggle Controls, Constants, Continuous Controls
EnumValue, EnumValues, EnumIndex | Selection controls
EnableOnPing | Confirm (OK) Objects
EnableEditing property | VEE Data Objects with "Enable/Disable Editing" control input pin
PopupPanelTitle | Main, UserFunctions, and UserObjects
Size and Location | PopupPanel for Main or UserFunctions
Tab index | VEE Objects in panel view
BackColor | UserFunction/UserObject panel view and Main panel view

All properties in the above table are called run-time properties. Different VEE objects have different run-time properties.

NOte

To GET/SET properties programmatically (except the Title property, EnableEditing property, EnableOnPing, EnumValue, EnumValues, Value and EnumIndex) of a VEE Object, the VEE Object must be added into a panel view first.

For Declare Variable objects, you cannot set their Declared Name or change their Variable Scope.

Generally, to set properties of VEE objects, you can use: Declared Name. property = property's value. For example DeclaredName.BackColor = "Blue".

For a UserFunction, although you cannot set the Declared Name or change the Variable Scope, you can set its properties by using its Title instead of the Declared Name. For example, To set BackColor for a UserFunction, you can use Title.BackColor ="Blue". Note that you can change the Title of a UserFunction.

Example: Setting the ForeColor of a X_Y Trace Object

1. Select Device [image] Virtual Source [image] Noise Generator.

2. Select Display [image] Waveform (Time). Set its Declared Name as waveform1 and add it into panel view.

3. Connect the data output of the Noise Generator to the data input of Waveform (Time) and run the program.

4. Select Device [image] Formula. Type in waveform1.BackColor = "blue".

5. Select Flow [image] Confirm (OK). Add it to panel view. Connect the sequence output pin of the Waveform to the sequence input pin of the Confirm (OK) object.

6. Run the program, the BackColor of the Waveform is changed to blue.

NOTE

For Confirm (OK) buttons, the EnableOnPing property is True by default, which means the Confirm button will be enabled when it is pinged. If the EnableOnPing property is set to False, the Confirm button cannot be pressed even when it is pinged.

In the following example, OK1 is a Confirm object and is disabled initially. In the Formula object, OK1's EnableOnPing property is set to TRUE. The OK1 button will be enabled after the OK button is pressed, because pressing OK button will ping the OK1 button.

If OK1's EnableOnPing is set to False in the above example, OK1 button will not be enabled even after the OK button is pressed.

See Also

Programmatic Properties, To Change Object's Name and Scope, Programmatic Properties, ProgrammaticPropertyDemo.vee, DemoTabIndexChangeDemo.vee


To Change Object's Name and Scope

To Change Object Declared Name or Declared Scope

Beginning with VEE 8.0, Properties window has two new items under Design tab. They are Declared Name and Declared Scope.

By entering a name in the Declared Name field in a VEE object's Properties window, you implicitly declared a variable for that VEE object. The variable is an Object data type, and it is local to the context where it exists.

To change properties of a VEE object at runtime, you must set the Declared Name for that VEE object first.

note

You can set the Declared Name for all VEE objects except Main, Declared Variable, and UserFunctions.

After setting the Declared Name of a VEE object, re-enter the Properties window for that VEE object, you can now change the Declared Scope of that object. By default the Declared Scope is Local to Context. You can change it to Global, or Local to Library if you are in a UserFunction. This capability makes it possible to use a VEE object declared in other context.

.NET objects and COM objects have Declared Name by default, so you can change their Declared Scopes without setting their Declared Names first.

Example

The following example defines an XY Trace Object in a UserFunction, and then changes the BackColor of the XY Trace to Green in Main.

1. Define an XY Trace in a UserFunction and connect a Function Generator to its input pin;

2. Set the Declared Name of this XY Trace as xy_uf and change its Declared Scope to Global; by default, the Declared Scope is Local to Context, which means you cannot access it outside of the UserFunction.

3. Set the BackColor of the XY Trace to Red in a Formula; then add the XY Trace to a panel view.

4. In Main, call the UserFuncion first. After 5 seconds delay, change the BackColor of the XY Trace to Green.

5. Run the program, you will see that at first the XY Trace is red, and then it turns to Green.

See Also

To Change Properties Programmatically, Programmatic Properties


Introduction to VEE

Introduction to Agilent VEE Programming

What Is Agilent VEE?

Welcome to Agilent VEE Pro. Agilent VEE is a graphical programming environment optimized for use with electronic instruments. The simplest way to state its value is the phrase, "Better measurements faster." Software prototyping is noticeably faster with Agilent VEE than with lower-level languages, and hundreds of powerful functions are available to help you analyze your measurement data.

Agilent VEE Building Blocks

Agilent VEE programs are created by placing graphical objects on the work area and wiring them together with lines. This graphical view is your program. You do not need to perform any cryptic and error-prone steps like preprocessing, compiling, or linking. Just make a "block diagram" and press Run.

VEE uses the term "objects" for the building blocks used in your program. VEE objects perform a wide variety of tasks, from adding numbers, to making logical decisions, to reading files, to displaying microwave spectra, to controlling instruments, and more. There are two general ways to create VEE objects: from VEE's Function & Object Browser and from VEE's drop-down menus.

The Function & Object Browser organizes over 200 VEE functions by category, such as "Trig," "Matrix," and "Data Filtering." It creates a Formula object preconfigured with the function you choose. Also available in the Function & Object Browser are over 1000 MATLAB functions.

An easy way to access the Function & Object Browser is to press the [image] button on the toolbar. Just click the desired Type, Category, and Function. Then press the Create Formula button to get an object which you place on the work area.

Over 450 other VEE objects are organized in five drop-down menus. Just click a main menu, follow the appropriate submenu (if any), click the desired object, and place it on the work area. Here is brief overview of the five drop-down object menus:

Flow These objects influence program flow. Some objects perform traditional execution control, such as conditional branching and looping. Others alter program and data timing with operations like delay and gate.

Device This is a grouping of miscellaneous objects. It includes useful submenus like Virtual Sources and ActiveX Controls. There are handy utility objects, like a counter, timer, and comparator. The Import Library and Sequencer objects are here. (If the object you want is not found in the first menu you check, look for it in the Device menu.)

I/O These objects interact with software and hardware outside the VEE application. This menu includes objects that communicate with instruments, files, printers, other processes, and more. The first menu pick is the powerful Instrument Manager.

Data These objects declare, generate, and access data. This menu includes graphical input objects (push buttons, knobs, sliders, etc.), constants of every data type, global variables, and handy functions like Unbuild Array, Merge Record, Concatenator, and more.

Display These objects help you view data. This menu includes graphical indicators (meters, thermometers, etc.), alphanumeric displays, waveform (oscilloscope) displays, various X-Y plots, polar spectrum displays, and more.

For an alphabetical listing of all VEE functions and objects, select the Contents and Index of this Help file and click on the "Reference" section.

Agilent VEE Programming Basics

VEE objects, the building blocks of a program, appear as rectangular boxes in the work area. These boxes perform the program actions. The boxes are connected by lines. These lines carry program data. Data travels out from the right side of an object (the output pins) and enters the next object on the left side (the input pins). Data always flows from left to right (as viewed by any given object).

An object performs its action(s) after all of its input pins have received data. After performing its action(s), the object sends data to all of its output pins. This cycle continues through the program diagram until all objects have finished all their actions. For a more detailed description of VEE program flow, see the Understanding Propagation topic.

Program flow in VEE's data propagation model is different from program flow in textual languages like C. Traditional languages forced programmers to define execution order at too low a level. Consider the simple example of assigning values to variables and calculating a sum. The C code segment for this task is:

a = 2;
b = 3;
c = a + b;

The syntax of C requires you to decide if "a" should be assigned first or if "b" should be assigned first. However, that detail really doesn't matter. Any order is OK, provided "a" and "b" both have data before they are added together. Programmers new to VEE are sometimes distracted by a perceived "lack of control" in a data flow model. Experienced VEE programmers become more efficient because they do not need to control these details.

Because an object cannot do its job until it receives all its data, all input pins must be connected to some data source. This calls attention to another important VEE feature: data type/shape conversions are handled automatically by the input terminals. For example, if an object expects floating-point data, and it receives integer data, its input terminals automatically convert the received data to the correct type. Although VEE provides optional ways to enforce type checking, the default behavior of input terminals frees you from the details of type checking and type conversion. The same is true for data shapes. An input pin can receive an array or a scalar value, and the object automatically takes the appropriate action. For more details about VEE's automatic data conversions, see the topic Converting Data Types on Input Terminals.

Agilent VEE and Instruments

The VEE programming environment strongly supports electronic instrumentation and measurement tasks. For those early prototyping stages, VEE provides simulated signal sources and displays. You can experiment with program flow and data processing without any external hardware. For more information, see the Virtual Source and Waveform Display topics, then follow their links to other simulated devices.

When you are ready for real-world data, VEE provides an Instrument Manager and a Dynamic I/O Server to simplify the tasks of discovering, configuring, and managing external instruments. VEE supports several types of instrument drivers and lets you choose the driver that best suits your preferences and/or the characteristics of an instrument. For those times when the instruments are not available, just press one button in the Instrument Manager to take a driver "off line" and continue developing your program. For more information:

See the Instrument Manager topic.

Select "How Do I..." [image] "Control Instruments" in the Contents of this Help file.

Select "Tell Me About..." [image] "Instrument Control Fundamentals" in the Contents and Index of this Help file.

Agilent VEE Programming Hints

Agilent VEE is a unique programming environment with some characteristics you may not have seen in other applications. If you are new to Agilent VEE, most of these unique characteristics will be pleasant surprises. Even so, many new VEE users find the following hints helpful:

The toolbar provides convenient buttons for program control, including:
(Run), [image] (Pause), [image] (Stop), and [image] (Step).

If you accidentally close the Main window, you can recover it with View [image] Main (or Ctrl-M).

A VEE program cannot run if any input pins are unconnected. If you do not want to connect an input pin, delete it.

If you accidentally pick the wrong object, press the Esc key to cancel. The remedy is the same for those rare times when you pick an object with no work area open to receive it. Press the Esc key to cancel the object and restore normal mouse operation.

The bottom line of the VEE window is a status bar. Develop the habit of checking that bottom status line for state information and helpful hints.

Learning More about Agilent VEE

Many resources are available to help you learn more about Agilent VEE. For example:

On-Line Tutorials
VEE provides multi-media tutorials which appeal to new VEE programmers. You can view them by selecting "Tutorials" from the Welcome Window. The Welcome Window appears (by default) when you start the VEE development environment. If VEE is already running, you can access the Welcome Window by selecting Help  [image] Welcome from VEE's main menu bar.

Example Programs
VEE provides more than 100 working programs as examples of various concepts. You can browse these examples by selecting "Example Programs" from the Welcome Window. Alternately, you can select "Guide to Agilent VEE Example Programs" in the Contents of this Help file.

On-Line Help Topics
This Help file provides many ways to locate information. The Contents tab presents an alphabetical "Reference," a "Tell Me About..." section on concepts, a "How Do I..." guide to tasks, and other useful sections. The Index tab makes it easy to search for specific topics, and a full-text search is available in the Find tab (for locating any word that didn't get its rightful place in the Index).

Classes
Agilent Technologies conducts many customer classes, including classes about VEE. For more information, select:
Help [image] Agilent VEE on the Web [image] Education/Training

See Also

Advantages of Using Agilent VEE


Advantages of Using Agilent VEE

Advantages of Using Agilent VEE for Test Development

Agilent VEE is a graphical programming language optimized for building test and measurement applications, and programs with operator interfaces. This release of the Agilent VEE product is for groups of engineers that need to create complex test and measurement systems.

VEE offers many advantages in test development:

• Increase your productivity dramatically. Customers report reducing their program development time up to 80%.

• Use VEE in a wide range of applications including functional test, design verification, calibration, and data acquisition and control.

• Gain instrument I/O flexibility controlling GPIB, VXI, Serial, GPIO, PC Plug-in cards, and LAN instruments. Use “panel” drivers, VXIplug&play drivers, “direct I/O” over standard interfaces, or imported libraries from multiple vendors.

• Use ActiveX Automation and Controls on PCs to control other applications such as MS Word, Excel, and Access that assist with generating reports, displaying and analyzing data, or putting test results into a database for future use.

• Increase throughput, build larger programs with ease, and become more flexible in instrument management. VEE has a compiler; a professional development environment suited for large, complex programs; and advanced instrument management capabilities.

• VEE supports Visual Studio .NET assembles, which means that any textual language that truly supports Visual Studio .NET is supported by VEE.

• You can further leverage your investment in textual languages because VEE also supports additional textual languages such as C/C++, Visual Basic, Pascal, and Fortran.

VEE programs are created by selecting objects from menus and connecting them together. The result in VEE resembles a data flow diagram, which is easier to use and understand than traditional lines of code. There is no laborious edit-compile-link-execute cycle using VEE.

The following two figures compare a simple function programmed first in a textual language (ANSI C) and then in VEE. In both cases, the function creates an array of 10 random numbers, finds the maximum value, and displays the array and maximum value.

The program in the ANSI C textual language:

/* Program to find maximum element in array */

# include <math.h>

main( )

{

double num[10], max;

int i;

for (i=0;i<10;i++){

num[i]=(double) rand( )/pow(2.0,15.0);

printf("%f/n", num[i]);

}

max=num[0];

for (i=0;i<10;i++){

if (num[i]>max) max = num[i];

}

printf("/nmax; %f/n", max);

}

The program in VEE:

In VEE, the program is built with program elements called objects. Objects are the building blocks of a VEE program. They perform various functions such as I/O operations, analysis, and display. When you view the objects with all of their connections, as shown in the above figure, this is called the detail view. The detail view is analogous to source code in a textual language.

In VEE, data moves from one object to the next object in a consistent way: data input on the left, data output on the right, and operational sequence pins on the top and bottom.

The objects are connected together to form a program. Follow the program from left to right. In the “Random” program shown above, a random number is added to the Collector - Create Array object ten times, creating an array. Then the program finds the maximum value in the array, and displays the Max Value and the Array Values.

Using VEE, with its modular programming approach, you can reduce the time it takes to create programs that control instruments, create customized data displays, and develop operator interfaces. This method of test development leads to productivity gains much greater than conventional techniques.

NOTE

In the above figure, some objects are displayed in detail, and some are displayed with only the name showing. The objects that are displayed in detail are shown in open view. Open view allows you to see the details of the object. To save space and increase program execution speed, you can iconize objects, or reduce them so that only the names are showing.

For example, in the above figure, the object labeled Random Number is shown as an icon. The object labeled Create Array is shown using an open view. The open view is larger and more detailed.

Creating Operator Interfaces in Agilent VEE

An additional benefit of programming in VEE is that it only takes a few minutes to create an operator interface.

Using the “Random” program above, the objects that the operator needs to see are selected and put into a panel view. A panel view shows only the objects the operator needs to run the program and view the resulting data. Following figure shows the panel view of the “Random” program above.

Note

The program and its operator interface are different views of the same VEE program. You can go back and forth from one view to the other by clicking the detail view and panel view buttons in the window title bar in VEE. Any edits or updates that you make to a program (detail view) are automatically made to the operator interface (panel view). You can also secure the operator interface from unwanted changes.

For more information about creating an operator interface, refer to “Creating a Panel View (Operator Interface)".

With VEE, you can perform certain tasks in minutes that might take days in a textual language.

• Create colorful, intuitive front ends to programs.

• Create operator interfaces that can be used with a keyboard and mouse, or keyboard input only.

• Choose from a wide assortment of user input and data display features.

• Use pop-up panels to create focus and conserve screen space.

• Secure programs from unwanted tampering.

• Use labels, choose colors and fonts, and add beepers, notepads, buttons, and switches in a variety of formats.

• Use your own or standard off-the-shelf ActiveX Controls for user input or displaying data.

Leveraging Existing Test Programs with Agilent VEE

On all supported operating systems, VEE provides mechanisms for linking conventional test programs as well as commercial applications. For example, you could use VEE to sequence existing tests in C, C++, Visual Basic, Fortran, or Pascal (or any compiled or interpreted language on your operating system). You can also use any language that truly supports Visual Studio .NET.

VEE also provides a number of interprocess communication features to share data with commercial applications such as databases or spreadsheets. VEE also supports standard ties to ActiveX Automation and Controls, and DLLs.

Controlling Instruments with Agilent VEE

VEE provides many options for controlling and communicating with instruments.

• Use panel drivers (instrument drivers) for over 450 instruments from different vendors plus all drivers available from various vendors that are VXIplug&play compatible in the Windows Vista, Windows 2000, or Windows XP.

• Use VEE's Direct I/O to send instrument command strings over standard interfaces such as GPIB (IEEE - 488), GPIO, RS 232, VXI, or LAN-based instruments for remote testing.

• Control PC plug-in boards from any manufacturer that supplies a Dynamic Link Library with the board.

• Use direct VXI backplane control using embedded PCs or workstations.

• Control a great variety of instrument types with an easy, organized instrument management capability.

Improving Test Capabilities with Agilent VEE

The VEE products offer the following features and benefits:

• Reduced development and maintenance time with graphical programming.

• Integration with conventional languages like C, C++, Visual Basic, Pascal, and Fortran.

• Convenient and flexible operator interface capabilities.

• Support for most popular test platforms.

• Use of ActiveX Automation and Controls.

• Agilent Technologies’ excellent array of support options.

• Easy and powerful documentation tools.

• Ease of porting test data to standard spreadsheets and word processors for reports.

• Interprocess communication tools to link with other applications such as relational databases or statistical analysis packages (versions 6.0 and later).

• Debugging tools that make the development and maintenance of large, complex programs efficient (versions 6.0 and later).

• Powerful test executive tools included with the product (versions 6.0 and later).

• Remote test capabilities with VEE's Web monitoring features (versions 6.0 and later).

• Unlimited runtime for distribution of your programs (versions 6.0 and later).

• Low cost site licenses (versions 6.0 and later).

See Also

Introduction to VEE, To Install Agilent VEE

Copyright (c) 1991-2006 Agilent Technologies, Inc.


Execution Modes1

Execution Modes

Execution Mode

Effect of Changing the Execution Mode

Related Reading

Execution Mode Changes: VEE 3 to VEE 4

Execution Mode Changes: VEE 4 to VEE 5

Execution Mode Changes: VEE 5 to VEE 6&7

Execution Mode Changes: VEE 6&7 to VEE 8


Execution Mode

Understanding Execution Mode

What is an Execution Mode?

Each VEE version has several Execution Modes. (They were called "Compatibility Modes" in previous versions). These modes allow a newer version of VEE to run programs created with an older VEE version exactly the same way the older VEE ran them. This is known as “backwards compatibility,” and all versions of VEE are 100% backwards compatible by using these Execution Modes.

For example, VEE version 4.0 had two Execution (Compatibility) Modes: VEE 3.x and VEE 4. This allowed VEE 4.0 to run old programs created with VEE version 3.0 (or prior) in the exact same way the programs ran in VEE version 3. If you want to run a VEE 3 program in Compiled mode, you switch modes, then VEE 4 runs your program under the Compiler.

In the same manner, VEE version 5.0 had three Execution (Compatibility) Modes: VEE 3.x, VEE 4, and VEE 5. In VEE version 6.0, VEE 6 Execution Mode is added to the list. A VEE program knows what version of VEE created it and what Execution Mode was used. When VEE loads that program, VEE puts itself into that corresponding Execution Mode, so the program will run exactly as it did in the older version of VEE.

Once a program is written and saved with an Execution Mode, the program retains that Execution Mode, unless changed by the user. For example, suppose you developed and saved a program in version 5.0. This program is saved with Execution Mode VEE 5. If you then load the program in version 6.0 and save it, the program still has Execution Mode VEE 5. Unless you change the Execution Mode (using the Default Preferences Dialog Box or other means), the Execution Mode does not change for the program, no matter which version of VEE loads the program.

VEE 6 Execution mode will work in VEE 7. Also, in previous VEE versions, it was sometimes possible to run a program created in a newer version of VEE in an older version. This depended upon which features the program contained. However, programs written in VEE 7 cannot be run in previous versions.

Why Should I Change Execution Modes?

You should change Execution Modes if you add new features to an existing program. For example, suppose you have a program written in version 5.0 (with associated Execution Mode VEE 5). To add new features (such as new data types) available in version 6.0, you should change the Execution Mode to VEE 6. If you change the program but do not change the Execution Mode, the new features added to the program may not run properly.

When Should I Change Execution Modes?

In most cases, programs written in previous versions of VEE will run 100% in newer versions of VEE as long as the Execution Mode is not changed. However, you may not be able to add new features unless the latest Execution Mode is used.

The following table shows the combinations of programs that will run for various versions and Execution Modes. Note that old programs will run in any version as long as the Execution Mode is not changed. The only potential problem occurs when the Execution Mode is switched.

Program Created in Execution Mode:

Running in VEE | VEE 4 | VEE 5 | VEE 6&7 | VEE8 | VEE 8.5
Version VEE 4 | runs | CNA | CNA | CNA | CNA
Version VEE 5 | runs | runs | CNA | CNA | CNA
Version VEE 6 | runs | runs | runs | CNA | CNA
Version VEE 7 | runs | runs | runs | CNA | CNA
Version VEE 7.5 | runs | runs | runs | CNA | CNA
Version VEE 8.0 | runs | runs | runs | runs | CNA
Version VEE 8.5 | runs | runs | runs | runs | runs

CNA means Compatibility Not Assured. Programs created on later versions of VEE might load and run on earlier versions of VEE, if they do not include any features unique to the later version. Programs which take advantage of newly added features will not run correctly on older versions of VEE, and in some cases, the programs may not even load into older versions of VEE. The point of Execution Modes is to assure that existing programs will run on newer versions of VEE. There is no assurance that new features will run on old versions of VEE.

Guidelines to Switching Execution Modes

When developing new programs, you should use the latest execution mode.

You can run any existing VEE program by selecting the applicable Execution Mode (VEE 3 for VEE 3.x programs, VEE 4 for VEE 4.x programs, or VEE 5 for VEE 5.x programs). The appropriate mode for older programs is automatically set when the program is loaded.

If you load a program which is set to VEE 5 or lower execution mode, and switch to VEE 6 Execution Mode, the old program may or may not run correctly. Most programs will run correctly. See the following example for a "bug fix" that may cause a program to run differently.

For example, suppose you have a version 5.0 program (Execution Mode VEE 5) which includes a To File that does a WRITE BINARY BYTE transaction. In version 5.0 (and prior versions), you could send "300" into this and get "44" written to the file. (This is technically a bug because "300" does not fit into a byte.)

In VEE 5 Execution Mode, you still get "44" to preserve program compatibility. However, in VEE 6 Execution Mode you get an error message saying VEE cannot convert 300 to a UInt8 (out of range).

Location

File [image] Default Preferences [image] Execution Mode

See Also

Execution Modes


Effect of Changing the Execution Mode

The following example demonstrates the increase in speed when a program is updated. This example focuses on the program speed without instrument I/O.

1 Open the chaos.vee program in the examples\Applications subdirectory.

This program illustrates explosive population growth. You can modify the program, as shown here, by using a Timer object to check the results. These examples were run using a 300MHz Pavillion PC on Windows 98 with two other large applications running concurrently.

The program execution is timed with the displays open in VEE 3 execution mode.

The next displays are iconized to improve speed without turning on the compiler. This cuts execution time about 1/6.

Finally, the compiler is turned on with the debugging features disabled. For optimum performance, check the Disable Debug Features box in File [image] Default Preferences when the program is fully debugged and ready to use.

The debugging features enable tools including the Show Execution Flow and Activate Breakpoints. When you check Disable Debug Features, this makes improvements in the size (in memory) and speed of the program. As you can see, the program runs about 12 times faster. These three figures show how you can get the best speed results by combining optimization techniques with the compiler.

In the next two programs, the VEE speed improvements use the compiler on areas of programs involving iterative scalar math routines. The example calculates the square root of a scalar value. (The result is not kept.) By using the compiler, the speed is approximately 107 times faster than using the VEE 3 execution mode.

VEE includes the execution modes because there are a few programming choices allowed in older versions of VEE that are not permitted in the current version (they now produce error messages). Furthermore, with some of the advances in the ActiveX Automation and Control capabilities, some programs that ran in VEE 4 or VEE 5 modes require minor modifications to run in VEE 6 mode. For details about the differences between the Execution Modes, refer to Tell Me About.... Execution Mode Changes in the Contents and Index under Help menu.

See Also

Execution Mode


Execution Mode Changes: VEE 3 to VEE 4

VEE programs written with versions before VEE 4.0 run exactly the same as they used to when run in VEE 3 mode. To ensure this, the interpreter is automatically enabled upon loading of older programs. This section describes the new functions and enhancements in VEE Version 4.0, that is, in VEE 4 mode.

Line Colors in Compiler Mode

In compiler mode, VEE assigns different colors to the data lines that connect objects based on the type of data flowing through the line. The default colors are listed below, along with the names of the color properties. You can change them in the Default Preferences dialog box, selected from the File menu. Choose the line you want to change in the Screen Element box, click on the Color Value box to open the color palette, and click on the color you prefer. Click OK to keep the new color for the selected line type.

  • Dark Sky Blue: numeric (Integer or Real type)

  • Dark Sky Blue: complex (Complex and PComplex type)

  • Med Orange: string (String type)

  • Med Dark Gray: sequence out (nil value, usually from a sequence out line)

  • Magenta: highlight

  • Black: unknown type or type that is not optimized (for example, Record types).

If the data type is an array, VEE displays a wider line. To increase speed, check your program for colored lines. The more non-black lines, the faster the program runs.

Potential Compatibility Problems

Programs written in versions before VEE 4.0 automatically run in VEE 3 mode. Programs written using VEE 4.x automatically run in VEE 4 mode. Programs written using VEE 5.x automatically run in VEE 5 mode. You can, however, change the Execution Mode of a program at any time.

Compatibility problems could arise in certain areas when changing an existing program from VEE 3 to VEE 4. The following paragraphs explain the potential problem areas. The information about using older versions of VEE is the same as when using interpreted mode or VEE 3 mode.

Time-Slicing UserFunctions

In versions before VEE 4.0, UserFunctions did not time-slice with other parts of the program. In compiled mode, UserFunctions will time-slice when called from separate threads. Be sure to use sequence pins between Call objects when parallelism is not desired.

UserFunctions only time-slice when called from Call, Formula, If/Then/Else, or Sequencer objects (only when called from the Function field). Breakpoints also now work in UserFunctions when called from Call or the other objects listed above.

UserFunctions will not time-slice, nor will breakpoints work, when called from a To File, To String, or similar objects or if the formula is supplied via a control pin.

If a UserFunction is executing and gets called again from another part of the program, that call will be blocked until the original call returns.

UserObjects

UserObjects would always time-slice in previous versions, but in compiled mode they will only time-slice when invoked from separate threads.

Function Precedence

The precedence of functions called from the Formula object has changed to the following:

1 Internal functions (like sin() and totSize())

2 Local UserFunctions

3 Imported UserFunctions

4 Compiled Functions

5 Remote Functions

In VEE 3 Execution Mode, internal functions are last in precedence. This allowed you to override internal functions such as totsize() or fft() with your own.

Auto Execute and Start

There are some subtle changes in behavior when using the Auto Execute feature of certain objects. In compiled mode, the behavior is as if the object was hooked directly to a Start object and that Start button was pushed. This change does not affect most programs.

OK Buttons and Wait for Input

Most asynchronous objects like the OK object or any object with Wait for Input enabled will work better in compiled mode in these two areas:

Stepping: In previous versions, stepping over such an object would often result in the termination of the program. In compiler mode, stepping works properly.

CPU usage: In previous versions, executing such an object usually resulted in increased CPU usage. In compiler mode, the CPU stays in an idle state.

Collectors Without Data

In previous versions, pinging the XEQ pin of a Collector that has never been pinged with data, outputs a nil container. In compiler mode, if the data type is known at compile time, you get a zero-element array of that data type. Otherwise, you get a zero-element array of type Integer.

This change allows the type inferences to be more consistent, producing better p-code downstream from the Collector object. Note that totSize() of a nil produces a one, while totSize() of a zero-element array produces a zero.

Sample & Hold Without Data

In previous versions, pinging the XEQ pin of a Sample & Hold object that has never been pinged with data yields a nil container. In compiler mode, the following error is generated (error number 937):

Sample & Hold was not given any data.

This change allows the type inferences to be more consistent, producing better p-code downstream from the Sample & Hold object.

Timer Object

In previous versions, the Timer object output an undefined result if the Time2 pin (the bottom data input pin) was pinged before the Time1 pin. In compiler mode, the Timer object generates an error if the pins are executed out of sequence.

Feedback Cycles

In compiler mode, a Junction object is required inside a feedback cycle. Start objects are no longer required. The following error is generated when feedback without a Junction is detected (error number 935):

A Junction is required inside of feedback cycles. Here are two examples.

VEE Version 4.0 and higher do not allow invalid connections, such as an object's data input pin connected to its data output pin or, for most objects, connecting a sequence output pin to a data input pin.

Parallel Threads

In VEE 3 Execution Mode, independent threads would round-robin between each thread, meaning that one object will be executed in one thread, then an object in the other thread, etc. In compiler mode, this behavior is not guaranteed.

Loop Bounds

To increase looping performance, the bounds of iterators (such as the Step field in a For Range object) are examined only at the beginning of the first iteration and not at every iteration. The object's fields are grayed at run time to show the value is not changeable. Data inputs to the iterators will be ignored if the value changes while the loop is running

For example, if the Step value of a For Range object is changed via the data input pin while the loop runs, it is ignored in VEE 4 and higher Execution Mode. In previous versions, the step value would have been checked on every iteration.

UserObjects and Calls With XEQ Pins

In versions before 4.0, you could have an XEQ pin on a UserObject or a Call object run the UserObject or UserFunction before all the data input pins were satisfied. The behavior of objects inside the UserObject or UserFunction connected to those unpurged data inputs was undefined. In VEE 4 and higher Execution Mode, this is not allowed. XEQ pins on those objects will generate an error. You can no longer add an XEQ pin to those objects.

OK Buttons With XEQ Pins

In versions before 4.0, an OK object with an XEQ pin was only executed once, when either the OK button was pressed or when the XEQ pin was sent data. In VEE 4 and higher Execution Mode, the OK button executes every time the XEQ pin is sent data. You can no longer add an XEQ pin to an OK object.

From File With EOF Pins

In versions before 4.0, the data output pin on a From File object was treated differently from other data output pins in VEE. If the From File was in a loop, the data on the output pin remained valid when the EOF data output pin was executed.

In VEE 4 and higher Execution Mode, the data output from a From File object is invalidated each time the loop executes (just like on all other objects). Therefore, when the EOF pin is executed, the data output is already invalid and cannot propagate.

Here is an example illustrates this situation. In versions before 4.0, the data fed into A on the Formula would have remained valid even while another iteration of the loop executed. To get valid data fed into B on the Formula, the EOF pin (on the bottom) executes and then the Formula executes

.

In VEE 4 and higher Execution Mode, the data fed into A is invalidated as soon as the next iteration of the loop begins. Because Formula does not get valid inputs on the same iteration of the loop, it never executes.

Parallel Junctions

In versions before VEE 4.0, if you had unconstrained objects that were connected in parallel to Junction objects, the order that you made the connections affected the execution order. In VEE 4 and higher Execution Mode, the order of connection does not matter.

Intersecting Loops

In versions before 4.0, you could intersect iteration objects. The execution order was undefined, but was affected by the order the connections were made. In VEE 4 and higher Execution Mode, only loops that intersect via a Junction object are allowed. Any other intersecting loops generate error 938. VEE was unable to compile this part of the program. See the following example.

Intersecting Loops Via Junctions

In versions before VEE 4.0, the example shown below would execute the Integer first. When the program encountered the Break, it would stop. In VEE 4 and higher Execution Mode, the example below runs the For Count objects after the Integer objects because the Break does not stop the program.

Open View Object Changes

In versions before VEE 4.0, you could change the data in open view fields while the program was running or paused. These changes would affect program behavior and the result was not guaranteed. In VEE 4 and higher Execution Mode, many objects do not allow this type of modification when the program is running or paused (the input fields are grayed). Some examples of this are:

  • Formula and If/Then

  • Collector

  • All Transaction objects' transactions

  • Get Mappings and Set Mappings

  • Get Values and Set Values

  • Constant's properties such as setting Scalar or 1D Array, Wait for Input, or Auto Execute.

  • Setting properties like Clear at PreRun

  • UserObject and UserFunction Trig Mode

  • Dialog Boxes properties

Adding or deleting input or output terminals on objects is grayed at run time (but not when paused). If this action is done at pause time, the program is stopped (as in versions before VEE 4.0).

Array Syntax in Expressions

Expressions with array syntax entered without commas, such as [1 2 3], will be reparsed when the program loads and automatically modified to use commas, as in [1,2,3]. This is true for programs in VEE 3 and VEE 4 modes.

See Also

Execution Mode Changes: VEE 4 to VEE 5, Execution Mode Changes: VEE 5 to VEE 6, Execution Mode Changes: VEE 6&7 to VEE 8


Execution Mode Changes: VEE 4 to VEE 5

In VEE 5.0, the VEE 4 and VEE 3 modes retain their compatibility definitions set in VEE 4.0. There are minor changes that will not affect existing programs that run in their original execution modes (VEE 3 or VEE 4). These changes are important to know if you plan to convert programs from older to newer modes.

About the VEE 5 Execution Mode

The VEE 5 Execution Mode is a superset of the VEE 4 mode. The VEE 5 mode retains the compiler features described previously and introduces significant changes affecting program compatibility. Most of the changes enable support for ActiveX automation and controls.

Other changes may impact your programming techniques if you use any of the features described in this section, even if you do not use ActiveX. For information about using ActiveX in VEE, see Using ActiveX Automation in VEE.

Converting Programs to VEE 5 Execution Mode

Old programs will automatically open in the appropriate old execution mode. If you want to change older programs to a newer mode, you must do this manually using Default Preferences under the file menu. When you change a program to VEE 5 mode, errors can occur. A list appears explaining problems. You need to fix these errors before VEE 6.0 accepts the switch to VEE 5 mode. VEE 6.0 does not automatically revise any part of your program to fix the errors.

VEE 5 Execution Mode Changes

To help you know how to fix errors, the VEE 5 mode compatibility changes are described below.

note

If you want to change VEE 3.x programs to VEE 5 mode, you should be sure they work in VEE 4 mode first and then change them to VEE 5 mode. See “Execution Mode Changes: VEE 3 to VEE 4" for help with that conversion.

Menu Changes

As part of the ActiveX support added to VEE 5.0, the Device menu has changed slightly. These new menu items have been added:

ActiveX Automation References…

ActiveX Control References…

ActiveX Controls

Also, the menu item Math & Functions that opened the Select Functions dialog box, is now called Function & Object Browser and opens the Function & Object Browser. You still use it the same way to select math operators and functions for a program, and its expanded functionality supports ActiveX.

Expressions

The following changes affect objects that contain expressions, such as Formula:

  • SET and ByRef are new keywords that are used for ActiveX automation. They are reserved and cannot be used as names for terminals.

  • New syntax is supported for ActiveX automation such as excel.worksheets(1).cells(1,2) = 2.

  • In VEE 3 and VEE 4 modes, expressions with array syntax entered without commas, such as [1 2 3], are reparsed when the program loads and automatically modified to use commas, as in [1,2,3]. In VEE 5 and higher modes, entering array syntax without commas, such as [1 2 3] will cause an error when Formula loses focus.

  • A value such as 1 returns an INT32, 1.0 returns a REAL64. Previously, both returned a REAL64.

  • There are two new built-in functions for ActiveX automation: CreateObject() and GetObject().

  • There are two new built-in constants for ActiveX automation:
    true and false.

Variables

The following changes affect variables:

  • When Delete Variables at PreRun is turned on (in Default Preferences), global variables are not deleted if they reference ActiveX controls.

  • The Declare Variable object has a new variable type called Object which is used for ActiveX automation.

  • The new Object variable type is also available on input terminals as a Required Type, though it cannot be coerced from or to another type.

Global Namespace

Global namespace rules have changed, which affects names given to variables, functions, and libraries in the following ways:

  • Local UserFunctions, Library names, global declared and undeclared variables, and local-to-library declared variables are now all in the same name space and must have unique names. This affects existing programs if they contain more than one instance of a name. For example, you cannot have a UserFunction and a declared global variable both named daily_results. This will cause an error when you switch the program to VEE 5 mode.

  • Within a Library, local UserFunctions and local-to-library declared variables are in the same namespace and must have unique names. This will cause an error when you switch the program to VEE 5 mode, or if you import a Library containing conflicting names into a VEE 5 mode program.

  • New syntax is allowed in the Formula object in all modes, such as

    lib.func(a,b) = RightHandExpr

    This parses correctly in all modes. However, it executes correctly only in VEE 5 and higher mode and causes a run-time error in VEE 3 and VEE 4 modes.

The changes in global namespace rules also change the order of precedence used in VEE 5 and higher mode to the following order when VEE looks up variable and function names used in a Formula:

1 Local input/output terminals.

2 Declared local-to-context variables.

3 Declared local-to-library variables when in a UserFunction context.

4 Global declared and undeclared variables, local UserFunctions, Library names, which all must be unique names.

5 Built-in functions, such as sin() and totSize().

6 ActiveX controls and automation constants depending on which libraries have been referenced using Device [image] ActiveX Automation References or ActiveX Control References. For example, many constants exist in Excel’s automation library, such as xlMaximized.

7 Imported UserFunctions, Compiled Functions, and Remote Functions appear in random order. To guarantee getting the correct one, include the imported Library’s name, as in myLib.func().

An unlikely example of how this new order can cause an older program to fail might involve a Formula containing the expression sin(90) with a data input terminal (a variable) named sin. In VEE 3 and VEE 4 modes, VEE ignores the input terminal name and calls the sin() built-in function.

However, VEE 5 and higher mode uses the new precedence order to look up the function and variable names. So VEE 7.0 looks up the terminal name, assumes it has an ActiveX object on the input, and tries to call the object’s default method. An expression that calls an ActiveX object’s default method, cells(1,1), is similar to sin(90). For information about ActiveX, see Using ActiveX Automation in VEE

READ TEXT Transactions

In VEE 3 and VEE 4 modes, the READ TEXT transaction using the TOKEN format with EXCLUDE CHARS does not advance the read pointer to exclude the specified character. Here is an example of this in VEE 4 mode:

This is an unexpected result. An expected result is for each phrase separated by the excluded character "*" to appear in separate AlphaNumeric displays, as shown in the VEE 5 mode example above.

Interaction Between To/From File and To/From DataSet

In VEE 3 and VEE 4 modes, a program using a To File or From File object with the EXECUTE REWIND transaction to access the same data file as a To DataSet or From DataSet object can cause unexpected interactions. More specifically, if a program uses From File (with EXECUTE REWIND) to read data from a file, then uses To DataSet to write data back into the same file, the data can be written incorrectly.

A similar interaction can happen when using From DataSet with To File. In VEE 5 and higher mode, this unexpected interaction is fixed so the data is written to the file correctly. However, we still do not recommend mixing To/From File with To/From DataSet operations on the same file.

See Also

E xecution Mode Changes: VEE 3 to VEE 4, Execution Mode Changes: VEE 5 to VEE 6, Execution Mode Changes: VEE 6&7 to VEE 8


Execution Mode Changes: VEE 5 to VEE 6

Execution Mode Changes: VEE 5 to VEE 6&7

In VEE 6.0, the VEE 5, the VEE 4, and VEE 3 modes retain their compatibility definitions set in VEE 5.0. There are minor changes that will not affect existing programs that run in their original execution modes (VEE 3, VEE 4,or VEE 5). These changes are important to know if you plan to convert programs from older to newer modes. They are described below.

About the VEE 6&7 Execution Mode

The VEE 6&7 Execution Mode is a superset of the VEE 5 mode. The VEE 6&7 mode retains the compiler features described previously and introduces significant changes affecting program compatibility. Most of the changes enable support for ActiveX automation and controls.

Other changes may impact your programming techniques if you use any of the features described in this section, even if you do not use ActiveX. For information about using ActiveX in VEE, see Using ActiveX Automation in VEE .

New Data Types

Int16, Real32, Variant, and UInt8 were new data types in VEE 6.0. All new data types and new transactions such as WRITE TEXT INT16 appear in all Execution Modes. However, new transactions behave the old way in old modes.

For example, in VEE 5 mode, WRITE BINARY INT16 actually does a WRITE BINARY INT32 and will not convert the data to an Int16. In VEE 6&7 mode, WRITE BINARY INT16 does convert data to an Int16. See Execution Mode for ways that the VEE Execution Mode could change program behavior.

Variant to VEE Data Type Conversion - Improved Array Handling

When data are returned from an ActiveX Automation Server (such as Excel) or an ActiveX control, VEE must convert the automation data types to VEE data types. With VEE 5.0, an array of Variants converted into a VEE Record. With VEE 6.0 (in VEE 6&7 Execution Mode), an array of Variants converts into a VEE array if all elements are of the same data type. (For mixed data types, there is no change from VEE 5.0 behavior.)

If all elements of an array are of the same data type, mapping of Variant data type to VEE array data type is as follows.

note

This feature is available in VEE 6&7 Execution Mode only.

Variant array member type | VEE 7.0 data type
VT_UI1 VT_BOOL VT_I2 VT_UI2 VT_I4 VT_UI4 VT_R4 VT_R8 VT_DATE VT_CY VT_BSTR VT_DISPATCH | UInt8 Int16 Int16 Int16 Int32 Int32 Real32 Real64 Real64 Real64 Text Object

However, there are still some gaps in the compatibility between new VEE 6&7 data types and ActiveX automation servers:

• Data types such as Boolean (VT_BOOL), Date (VT_DATE), Currency (VT_CY), and Error (VT_ERROR) do not have built-in VEE data type counterparts. Use of these data types with "ByRef" in ActiveX is supported with the Set functions and Query functions described below.

• Certain special Variant values such as Empty (VT_EMPTY) and NULL (VT_NULL) have no equivalent and cannot be uniquely identified.

Set Functions

The Set functions tell VEE that during ActiveX automation operations the containers returned by these functions will be given special treatment. The set functions are:

asVariantBool()

asVariantCurrency()

asVariantDate()

asVariantError()

asVariantEmpty()

asVariantNull()

Query Functions

Query functions are used on containers created from the return values of automation methods and properties. The Query functions are:

isVariantBool()

isVariantCurrency()

isVariantDate()

isVariantError()

isVariantEmpty()

isVariantNull()

Updated Functions

The following functions were updated in VEE 6.0.

whichOS() — updated with return values of "Windows_98" and "Windows_2000".

createObject() — updated with an optional second parameter that specifies the name of a remote host computer.

See Also

E xecution Mode Changes: VEE 3 to VEE 4, Execution Mode Changes: VEE 4 to VEE 5, Execution Mode Changes: VEE 6&7 to VEE 8


Execution Mode Changes: VEE 6&7 to VEE 8

In Agilent VEE 8.0, the VEE 6&7, the VEE 5, the VEE 4, and the VEE 3 execution modes retain their compatibility definitions set. There are minor changes that will not affect existing programs that run in their original execution modes. These changes are important to know if you plan to convert programs from older to newer modes. They are described below.

About the VEE 8 Execution Mode

The VEE 8 Execution Mode is a superset of the VEE 6&7 mode. The major change is that VEE 8.0 introduces two data types.

New Data Types

Int64 and Boolean are new data types in Agilent VEE 8.0.

Int64 represents the value from -9223372036854775808 to 9223372036854775807 and has 22-bit data precision.

Boolean represents a value that only can be True or False.

New transaction format WRITE TEXT INT64 and WRITE TEXT BOOLEAN are added to transactions at all execution modes. At every execution mode, the input data will be converted to Int64 or Boolean. See Execution Mode for ways that the VEE Execution Mode could change program behavior.

Integer Constant Operation

Integer constant operations may return different data types at VEE 8 mode.

Operation | Data Type
MaxInt32+1 | Int64
MaxInt32-1 | Int32
MaxInt64+1 | Data Overflow #514 error
MaxInt64-1 | Int64
MinInt32-1 | Int64
MinInt32+1 | Int32
MinInt64-1 | Data Overflow #514 error
MinInt64+1 | Int64

Build-in Numeric Constant

True and False are of Boolean data type at VEE 8 Execution Mode. It can be used to set .NET or COM properties directly. For example, you can set the ShowLine property of TreeView in a formula like this:

TreeView.ShowLines = true;

MaxInt64 and MinInt64 provide maximum Int64 Constant or minimum Int64 Constant.

.NET operation builder will use True/False for Boolean data type at VEE 8 mode instead of asVariantBool( ) in VEE 6&7 mode.

Variant to Agilent VEE Data Type Conversion - Added VT_I8

Variant array member type | Agilent VEE 8.0 data type
VT_UI1 VT_BOOL VT_I2 VT_UI2 VT_I4 VT_I8 VT_UI4 VT_R4 VT_R8 VT_DATE VT_CY VT_BSTR VT_DISPATCH | UInt8 Boolean (New in Agilent VEE 8.0) Int16 Int16 Int32 Int64 (New in Agilent VEE 8.0) Int32 Real32 Real64 Real64 Real64 Text Object

Two New built-in Type Conversion Functions

asBoolean()

asInt64()

See Also

E xecution Mode Changes: VEE 3 to VEE 4, Execution Mode Changes: VEE 4 to VEE 5, Execution Mode Changes: VEE 5 to VEE 6


Execution Mode Changes: VEE 8 to VEE 85

Execution Mode Changes: VEE 8 to VEE 8.5

In Agilent VEE 8.5, the VEE 8, the VEE 6&7, the VEE 5, the VEE 4, and the VEE 3 execution modes retain their compatibility definitions set. There are minor changes that will not affect existing programs that run in their original execution modes. These changes are important to know if you plan to convert programs from older to newer modes. They are described below.

About the VEE 8.5 Execution Mode

The VEE 8.5 execution mode is a superset of the VEE 8 mode. The major change is that VEE 8.5 introduces a new data type.

New Data Type

UInt16 is the new data type in Agilent VEE 8.5. UInt16 represents the value from 0 to 65535.

New transaction format WRITE TEXT UINT16 is added to transactions at all execution modes. At every execution mode, the input data will be converted to UInt16. See Execution Mode for ways that the VEE Execution Mode could change program behavior.

Note

VEE supports data type conversion according to automatic promotion rule. UInt16 is not a subset of Int16 and vice versa. In order to support the operation between UInt16 and Int16 smoothly, the rule is to promote the two data types into higher data type -- Int32. See the picture below for example, the output data type is Int32.

Variant to Agilent VEE Data Type Conversion - Added VT_UI2

Variant array member type | Agilent VEE 8.5 data type
VT_UI1 VT_UI2 VT_BOOL VT_I2 VT_UI2 VT_I4 VT_I8 VT_UI4 VT_R4 VT_R8 VT_DATE VT_CY VT_BSTR VT_DISPATCH | UInt8 UInt16 (New in Agilent VEE 8.5) Boolean Int16 Int16 Int32 Int64 Int32 Real32 Real64 Real64 Real64 Text Object

One new built-in Type Conversion Function

asUInt16()

Changed the way VEE calculates a sample interval

VEE 8.5 execution mode corrects the way VEE handles waveform data (time-sampled data mapped over time).

In VEE 8 execution mode and before, VEE uses the wrong number of points to calculate a sample interval when displaying a waveform and when doing any kind of signal processing. For example, in the following program, the X marker value reads 0.9375m when it should read 1m.

The reason is that the sample interval is calculated as timeSpan / number of points, yielding the incorrect sample interval 0.000625 (0.001/16). That's why the X marker value reads 0.9375m (0.000625*15).

Actually, the sample interval should be calculated by the formula timeSpan / (number of points – 1). There are 16 points, the sample interval should be 0.001/(16-1) = 6.667e-5 and the X marker should be 1m.

In VEE 8.5 execution mode, VEE has solved this problem and can give the correct sample interval. The following figure shows the same program in VEE 8.5 execution mode. The X marker reads 1m.

See Also

E xecution Mode Changes: VEE 3 to VEE 4, Execution Mode Changes: VEE 4 to VEE 5, Execution Mode Changes: VEE 5 to VEE 6,Execution Mode Changes: VEE 6&7 to VEE 8.


Related Reading

For more detailed information about instrument control topics discussed in this manual, refer to the following publications.

• Tutorial Description of the Hewlett-Packard Interface Bus (Hewlett-Packard Company, 1987), part number 5021-1927.

This document provides a condensed description of the important concepts contained in IEEE 488.1 and IEEE 488.2. If you are unfamiliar with the IEEE 488.1 interface, this is the best place to start.

• IEEE Standard 488.1-1987, IEEE Standard Digital Interface for Programmable Instrumentation (The Institute of Electrical and Electronics Engineers, 1987).

This standard defines the technical details required to design and build a GPIB (IEEE 488.1) interface. This standard contains electrical specifications and information on protocol that is beyond the needs of most programmers.

• IEEE Standard 488.2-1987, IEEE Standard Codes, Formats, Protocols, and Common Commands For Use with ANSI/IEEE Std 488.1-1987 (The Institute of Electrical and Electronics Engineers, 1987).

This document describes the underlying message formats and data types used by instruments that implement the Standard Commands for Programmable Instruments (SCPI).

• IEEE Standard 728-1982, IEEE Recommended Practice For Code and Format Conventions For Use with ANSI/IEEE Std 488-1978, etc. (The Institute of Electrical and Electronics Engineers, 1983).

• VMEbus Extensions for Instrumentation, including: "VXI-0, Rev. 1.0: Overview of VXIbus Specifications" and "VXI-1, Rev. 1.4: System Specification," VXIbus Consortium, Inc., 1992.

• HP VISA User's Guide (Hewlett-Packard Company, 1998), part number E2090-90035.

This document is useful for users who create their own VXIplug&play drivers and provides additional information about addressing and using VXIplug&play drivers.


About the Compiler

To use the compiler and include ActiveX automation and controls, set Execution Mode to VEE 6&7 or higher. If you want to convert VEE 3 programs to VEE 8 mode, you should make sure they work in VEE 4 ,VEE 5 , and VEE 6&7 modes first, as there are some program execution differences between each mode.

note

It is not necessary to understand the information in this section to use the compiler. This section explains the concepts behind the compiler for your information only. Information about the compiler applies to VEE 4 and higher modes, except for minor changes.

The compiler works with programs that run in VEE 4, VEE 5, VEE 6&7, or VEE 8 modes. The VEE compiler converts a VEE program into p-code, but there is no machine language or executable generated.

The compiler allows VEE to:

• Predict at compile time (instead of determining at run time) the order of execution of objects

• Determine what data types will be flowing on certain data lines

• Optimize code generation

• Generate and execute the most optimal p-code for any given VEE object.

VEE programs compile transparently when you press the Run button. Stepping and breakpoints are fully supported, as well as Show Execution Flow, Show Data Flow and Line Probe.

Subsequent runs of the same unmodified program do not require recompilation. When a program is modified only the contexts needing recompiling are recompiled (much like an incremental compiler). Most programs benefit from the use of the compiler, though the actual results vary. For example, a program using many levels of nested loops may see a greater speedup than one that does a lot of I/O or screen updates (e.g., displays).

In compiled mode, iterators and formulas gain the most execution speed benefit. A program written with a previous version of VEE may not run exactly the same way with the compiler. This could be due to specific programming techniques, use of undocumented side-effects, or even slight changes in documented behavior.


Instrument Control Fundamentals

VEE supports several types of objects for communicating with instruments.

This table gives an overview of the differences between these instrument control objects.

VEE Object | Instrument Access | Main Benefits | Supported Interfaces
Direct I/O | Communicates directly with any instrument. | Fast I/O. Can control any instrument. | GPIB, Serial, GPIO, VXI, and LAN.
To/From VXIplug&play | Requires a VXIplug&play driver supplied from the instrument manufacturer specific to each platform. Requires VISA to be installed. | Fast I/O. Drivers can be used by multiple software applications. | GPIB, VXI, USB, LAN, and Serial.
IVI-COM Driver | Communicates with instruments having IVI driver installed | Instrument interchangeability | GPIB, VXI, LAN, USB, Serial
NIDAQ Driver | Drivers talk to National Instruments cards via several different interface types. | Easy to use NI instruments | NI-DAQmx, NI-DMM, NI-SCOPE, NI-FGEN, NI-SWITCH and Traditional NI-DAQ
Multi-Instrument Direct I/O | Communicates directly with multiple instruments. | Fast I/O. Can control any instrument. | GPIB, Serial, GPIO, VXI, and LAN.
Panel Driver | Requires an Instrument Panel Driver supplied with VEE.b | Easy to use. | GPIB and VXI.
Component Driver | Requires an Instrument Panel Driver supplied with VEE. | Faster I/O than Panel Driver. | GPIB and VXI.
PC Plugin Card Driverc | Requires an ODAS driver supplied by the instrument manufacturer. | Fast I/O. Drivers can be used by multiple software applications. | PC plugin slots

b. Panel Drivers are also sometimes called "VEE drivers."

c. There is no longer PC plug-in card support in VEE 8.0

The To/From VXIplug&play, Panel Driver, Component Driver,IVI-COM Driver, NIDAQ Drive,and Plug&Play Driver objects allow you to control instruments without learning the details of the instrument's programming mnemonics and syntax. If you prefer to communicate with your instruments by sending low-level mnemonics, or if a driver is not available for your instrument, you can use Direct I/O.

note

You can use all these methods to communicate with different instruments within a VEE program. However, do not use VXIplug&play drivers along with any of the other methods to communicate with the same instrument in the same program — unexpected results may occur.

See Also

I ntroduction to Direct I/O, Introduction to Panel Drivers and Component Drivers, Introduction to VXIplug&play


Introduction to Direct I/O

Direct I/O objects allow you to read and write arbitrary instrument data in much the same way you read from and write to files. This allows you full access to any programmable feature of any instrument. No instrument driver file is required, but you must have a detailed understanding of your instrument's programming commands to use Direct I/O. In order to use Direct I/O to communicate with GPIB, VXI, or Serial devices, the I/O libraries must be installed.

Direct I/O objects also provide convenient support for learn strings. A learn string is a special feature supported by some instruments that allows you to set up measurement states from the front panel of the physical instrument. Once the instrument is configured, you simply select Upload from the Direct I/O object menu to upload the entire measurement state of the instrument to VEE. You can recall the measurement state from within your program by using the Direct I/O object.

An Example of Direct I/O

The following figure shows a Direct I/O object set up to obtain the identification string from an HP 34401A Multimeter:

The first transaction in the Direct I/O object writes the text string *IDN? to the HP 34401A at GPIB address 722. This causes the HP 34401A to send the identification string, which is read by the second transaction and output to the AlphaNumeric object.

For information about how to configure VEE to use Direct I/O, see Configuring for a Direct I/O Object For details about how to use the Direct I/O object, see Using the Direct I/O Object .

MultiInstrument Direct I/O

The MultiInstrument Direct I/O object lets you control several instruments from a single object using direct I/O transactions. This object looks the same as the Direct I/O object, except that each transaction in the MultiInstrument Direct I/O object can address a separate instrument.

The object is a standard transaction object, and works with all interfaces that VEE supports. Since the MultiInstrument Direct I/O object does not necessarily control a single instrument, the title does not list an instrument name, address, or live mode condition.

By using MultiInstrument Direct I/O, you can reduce the number of instrument-specific Direct I/O objects in your program. The resulting performance increase is especially important for the VXI interface, which is faster than GPIB at instrument control.

Figure that follows shows the MultiInstrument Direct I/O object and its I/O Transaction dialog box. The object is being set up to communicate with an HP E1413B, HP E1328, and HP 3325.

For further information about using the MultiInstrument Direct I/O object, see “Using the MultiInstrument Direct I/O Object".


Introduction to VXIplug&play

VXIplug&play is an interface specification that allows multiple vendors to supply compatible hardware and software. A VXIplug&play driver is a library of functions for controlling a specific instrument. The driver is written by the hardware vendor and shipped with the instrument.

VXIplug&play drivers can be written for non-VXI instruments.

VEE Version 3.2 through VEE 6.0 support drivers that comply with the WIN95/98, or WINNT, VXIplug&play specification version 3.0 or later. VEE version 7.0 does not support HP-UX or Windows 95. VEE version 8.0 supports Windows XP or Windows 2000. Windows 98 and Windows NT are not supported by VEE version 8.0. VEE version 8.5 supports Windows Vista, Windows 2000, and Windows XP.

Getting Started

Before you can get started with VXIplug&play, you must have completed these steps:

1 Install the interface (GPIB or VXI).

2 Install VISA. If you are using an Agilent interface card use VISA as supplied with VEE. See Installing the Agilent I/O Libraries (VEE for Windows) for details. Otherwise, you must install VISA as supplied with the interface card.

3 Configure VISA for each hardware interface. If you are using an Agilent interface card follow the instructions in Installing the Agilent I/O Libraries. Otherwise, you must configure VISA as specified by the interface manufacturer.

note

VISA (Virtual Instrument Software Architecture) is an I/O library that VXIplug&play drivers use to control instruments. VISA is required for VXIplug&play and provides VISA function calls which are used by the VXIplug&play drivers.

What You Need

VEE needs these four files for each VXIplug&play driver.

• The library file

• The function panel file

• The header file

• The help file

The files installed with each VXIplug&play driver always include these files. Other files are also installed.

note

Not all VXIplug&play drivers support all frameworks (platforms). Also, certain versions of VISA may not be supported on all frameworks. Please check with the appropriate vendor.

Installing the VXIplug&play Driver Software

To install the set of files needed for each driver, follow the instructions included with the driver by the instrument manufacturer.

Location of Files

The VXIplug&play files are located under the WINNT\ directory. This location is relative to the root drive and directory value stored in the registry by the VISA installation. The default value for the root drive and directory is C:\Program Files\VISA\.

This table shows the VXIplug&play driver files needed by VEE:

Filenamea | Location | Purpose
PREFIX_32.DLL | BIN | Instrument driver library
PREFIX.FP | PREFIX | Instrument driver function panel file
PREFIX.H | INCLUDE | Instrument driver header file
PREFIX.HLP | PREFIX | Instrument driver help file

a a. PREFIX refers to the name of the instrument such as HPE1410.

Summary of Terminology

Working with VXIplug&play drivers is different than using other types of I/O with VEE. Here is a summary of how the different pieces fit together.

• The VEE program calls VXIplug&play functions.

• The functions (that have parameters that may be set via function panels) are part of the VXIplug&play driver. The functions talk to the instrument through the VISA software.

• The instrument passes data back through VISA and into the function parameters.

A VXIplug&play Example Program

Following figure shows an example program that uses the To/From VXIplug&play object to initiate a voltage measurement and to obtain a reading from the HP E1410A Multimeter.

Further Information

For information about how to configure VEE to use VXIplug&play, see Configuring of a VXXIplug_play_Driver. For further information about how to use VXIplug&play in VEE, see Running a VEE Program and Using VXIplug&play Functions from Call Objects .


Overview

Program Compatibility:

Previous versions of VEE have supported VXIplug&play drivers. VEE Version 3.2 provided the To/From VXIplug&play object. VEE 3.2 programs using this object are compatible with later versions of VEE.

VEE Version 3.1 provided only direct Call access to VXIplug&play drivers. If you used Call objects to control VXIplug&play instruments in VEE Version 3.1, your program will work in later versions of VEE after you make certain changes to use the 32-bit version of the driver.

You must install the 32-bit version of the VXIplug&play driver, and you may have to change the Import objects to use the new location of the VXIplug&play driver files. For more information on using Call objects to access VXIplug&play drivers, see Using VXIplug&play Functions from Call Objects.

To use a VXIplug&play driver to communicate with an instrument, you must install the appropriate VXIplug&play driver files and the VISA I/O library. See Introduction to VXIplug&play for VISA installation information. You must also configure VEE for the instrument as described in Configuring for a VXIplug&play Driver.

The primary means of communicating with a VXIplug&play driver in VEE is the To/From VXIplug&play object, described in the following section. You can also call VXIplug&play functions from VEE Call objects (see Using VXIplug&play Functions from Call Objects.) The latter method is provided for backward compatibility with VEE Version 3.1.


Running a VEE Program

The transactions in the To/From VXIplug&play object execute from top to bottom. This section explains what happens when To/From VXIplug&play objects execute.

Initializing and Closing Drivers

The first time you run a program after you load or create it, a delay occurs to initialize each instrument controlled with To/From VXIplug&play objects. This initialization sets the instrument to a known initial state. Each subsequent time you run the program, your program executes normally, without performing the initialize actions.

Each instrument controlled by the program must be initialized once in a VEE session. The VXIplug&play Resource Manager does an "instrument find" to verify the instrument is connected to the address and to set the instrument to a known state. This will take an indeterminate amount of time, possibly up to 10 seconds per instrument. This delay happens the first time the To/From VXIplug&play object for each instrument is executed.

Because the initialization is only performed once per VEE session, you should execute functions (such as clear or reset) that set an instrument to a known state every time the program runs. When you load another program or exit VEE, the VXIplug&play drivers are automatically closed.

Advanced Initialization Information

This section explains some of the details behind some of the VEE implementation of VXIplug&play initialization. Understanding these concepts is not required to successfully write a VEE program that uses VXIplug&play drivers.

Each VXIplug&play driver is required to have a PREFIX_init() and a PREFIX_close() function. These functions are called automatically by VEE.

The purpose of the init() function is to set your instrument to a known state and to get a "session handle". Each instrument specified by a VEE Name, when configured, has a unique session handle assigned the first time it is executed in a program. That session handle is used through the program to uniquely identify that instrument.

All To/From VXIplug&play objects communicating with the same instrument (with the same VEE Name) are identified by the same session handle. The session handle is shown in the vi field in the lower left corner of Panel tab of the function panel. VEE automatically takes care of passing this session handle between the various To/From VXIplug&play objects.

Because the init() call is usually a lengthy operation, it is only called when necessary. When the first To/From VXIplug&play object is executed in a program, the appropriate init() function is called. When init() is called, it may also perform an Identification Query and/or a Reset depending on how you configured the driver.

The purpose of the close() function is to close the session handle (there are a limited number of them), take the instrument off-line, clear any data associated with the instrument, and perform instrument-specific actions, if needed. VEE calls the close() function at the following times:

• After New, Open, or Exit is selected.

• When all To/From VXIplug&play objects for a single VEE Name (such as dvm) are deleted.

• When the Address or init() parameter values are changed in the VXIplug&play Instrument Properties dialog box. In this case, close() is called so that init() will be called again with the new values.

Error and Caution Checking

After each transaction is executed, the function returns a status value to VEE, which automatically checks this value. If the value indicates that the function executed successfully, the next transaction executes.

Error Checking If the status value returned indicates an error, VEE stops the program and reports the error. If you have an error output pin to trap the error, the error output pin propagates instead of stopping the program. Use the errorInfo() object to get the details of the error message.

VEE automatically calls the PREFIX_error_message() function to get as much error information from the VXIplug&play driver as the manufacturer includes. This information is output in the VEE error message or from errorInfo().

note

After an error occurs the instrument is left in an unknown state. Unless you call specific reset or clear functions at the beginning of your program, you will not know the state of your instruments the next time you start the program.

Caution Checking If the status value returned is a caution, the program pauses and displays a caution dialog box. The caution dialog box contains information from the instrument manufacturer and lets you choose to continue running the program or stop.

Caution messages cannot be trapped programmatically. However, if you are aware of the common caution messages from the driver, you can handle them in the VEE program. For example, if you get a caution message that the instrument is not ready to let you read data, you can use a Delay object or put the To/From VXIplug&play object in a loop to retry reading.

If you handle a known caution condition in the VEE program, you may want to suppress the caution message dialog box. To do this, from the To/From VXIplug&play object's Properties dialog box select the check box for Ignore Cautions Returned.

note

Generally, ignoring caution messages (by checking the Ignore Cautions Returned check box) is not necessary and, unless you are sure of how to handle the caution condition in your program, is discouraged.

Passing Parameters

According to the VXIplug&play specification, you must allocate memory and pass it to the driver before requesting data. Some VXIplug&play functions place the data read into an array. Most of these VXIplug&play functions also have a parameter that specifies the size of the array sent in and will error if the array is not big enough. In this case, you may allocate an array of any size and tell the function how big it is. The function will then write data into the array only to the size specified.

Caution

Other VXIplug&play functions assume the array passed in is big enough for the data read and write to it regardless of its size. This is especially common for Text strings. If insufficient memory is allocated, this action will overwrite memory and cause a General Protection Fault or Segmentation Violation. Since the VXIplug&play DLL is linked directly into VEE, this situation can cause VEE to crash and exit.

note

The most straightforward method to allocate memory for an array or string data input is to use the Auto-Allocate feature. See “Getting Help on a VXIplug&play Function Panel". You still need to determine the size to allocate, but once you specify the size, the memory is allocated automatically.

Find out how much memory you need for your data by reading the driver's help file. Select Instrument Help from the To/From VXIplug&play object's object menu. This help file tells you how large the array must be.

If you do not use Auto-Allocate, you must create an object to allocate the memory and connect it to the data input terminal of the To/From VXIplug&play object:

• For an array input, use an Alloc Array object of the appropriate type, and set the size appropriately.

• For a string input, use a Formula object. Delete the data input terminal from the Formula object and enter an expression like 256*"a". This creates a string that is 256 characters long (plus a null byte) filled with a’s. Most VXIplug&play functions will not write more than 256 characters into a Text parameter. However, it is best to check the help on each function panel that requires a Text input to be sure.

An Example Program

The following figure shows a simple program that uses To/From VXIplug&play objects to communicate with the HP E1410A VXI Multimeter:

Limitations to VXIplug&play

There are some limitations to using VXIplug&play drivers in VEE.

• Because the Agilent IO Monitor does not show any I/O from VXIplug&play drivers. VXIplug&play drivers are C programs that are linked into VEE. We recommend that you use a hardware bus monitor, if needed.

• Some optional features that are not required by the VXIplug&play specification, such as callbacks, are not supported by VEE.

• All I/O [image] Advanced I/O objects (including Interface Operations, Instrument Event (SPOLL), and Interface Event) are not supported for VXIplug&play.

• VXIplug&play does not support the concept of LIVE MODE/NOT LIVE MODE. When you run a program, all instruments used in your program must be connected to your computer. However, you can open a program without the instruments used in the program being connected. Also, you can create a program without having the instruments connected. You can use To/From VXIplug&play objects and specify the function calls as long as the VXIplug&play driver is installed.

• You cannot use VXIplug&play drivers and any of the other VEE instrument control methods (Direct I/O, Panel Driver, or Component Driver objects) to communicate with the same instrument in the same program. However, you can use VXIplug&play drivers for one instrument and other instrument control methods for other instruments in the same program.

note

The VXIplug&play specification is continually being updated and enhanced. New features may be voted into the specification by the VXIplug&play consortium between revisions of VEE. Because the VXIplug&play specification does not specify that revision information should be included in the driver library, VEE cannot check the driver for compatibility. Therefore, you need to check with the instrument manufacturer to make sure the driver conforms to the currently supported VXIplug&play specification.


Using VXIplug&play Functions from Call Objects

You may want to use VXIplug&play with a VEE Call object for the following reasons:

• Existing Program Compatibility: If you have existing programs using VXIplug&play that were created using VEE Version 3.1, you may want to continue to use them with minimal modifications. However, if you plan to maintain these programs over the long term, it would be better to rewrite them using the standard function panel access in the To/From VXIplug&play object as described in “Using the To/From VXIplug&play Object".

• Access to Older Drivers: Some earlier versions of non-HP VXIplug&play drivers (1995 and earlier) were written to earlier versions of the VXIplug&play specification. You can still access these drivers through the VEE Call object.

Except for the reasons listed above, you should use VXIplug&play drivers with the methods described in “Using the To/From VXIplug&play Object".

Using a Dynamic Link Library or Shared Library in VEE

This section will show you the steps in loading a VXIplug&play driver into VEE once the required files are installed.

To use a VXIplug&play driver in a VEE program, do the following:

1 Import the library.

2 Run the routines which use the library.

3 Delete the library when the program is done.

The three VEE objects associated with these steps are Import Library, Call, and Delete Library.

Importing the Library

Before you can use a Call object (or Formula object) to execute the driver, you must import the function into the VEE environment via the Import Library object.

In the Import Library object, under Library Type, select Compiled Function. Enter the path and name of PREFIX.h using the Definition File button. See Location of Driver Files.

Then, select the path and name of PREFIX_32.DLL using the File Name button. The Library Name button assigns a logical name to a set of functions. It is recommended that the name be PREFIX, where PREFIX refers to the name of the instrument, such as HP E1410.

Before using a driver with the Call object, you must configure the Call object. The easiest way to do this is to select Load Lib from the Import Library object menu to load the driver file into the VEE environment. Bring up a Call object from the Device menu. Then, select Select Function on the Call object menu. VEE will bring up a dialog box with a list of all the functions listed in the header file that are exported from driver file.

Calling a VXIplug&play Driver from VEE

Use a Call object to make the calls to a VXIplug&play driver.

Sequence of Calls The sequence of calls for a VXIplug&play driver is very important. The sequence is:

1 Call the initialize function. (This function returns a session handle.)

2 Perform calls to the driver using the handle returned by the initialization function.

3 Call the close function.

Initialize Function The initialize function PREFIX_init has three input pins and two output pins.

The three input parameters are:

• Instrument Address

See “Configuring for a VXIplug&play Driver" for information about VXIplug&play addressing.

• Identification Verification Flag

If the verification flag is 1, the initialize function checks the identity of the instrument. This is to be done by checking the manufacturer ID and model number, using the "*IDN?" query, or other means specified by the instrument manufacturer. Set the flag to 0 if the check should not be done.

• Reset Flag

The reset flag should be 1 if the initialize function is to place the instrument in a pre-defined state. Set the flag to 0 if the reset should not be done.

The two output parameters are:

• Return Value

VXIplug&play defines the return value from a VXIplug&play driver to be the status of the operation performed. The integer returned can be translated into a meaningful message by calling PREFIX_error_query from a separate Call object. If the return value is 0, the init() call was successful.

• Handle for VXIplug&play Functions

If the return value from the initialize function is 0, the output parameter contains an instrument handle. An instrument handle is simply a number which associates a function call with this initialization. Most VXIplug&play functions require this handle as an input parameter.

Each initialization returns a unique handle in the output parameter vi. The parameter may be called by a different name, such as session handle, but it is always the last parameter returned from the init() function. When the close() function is called, the handle is returned to the system.

Calling VXIplug&play Functions Other functions can be called using the Call object. For each function called, the handle from the PREFIX_init function must be provided to the instrID input pin of the Call object.

Using Other Common VXIplug&play Functions Besides the PREFIX_init and PREFIX_close functions, VXIplug&play drivers may implement other common driver functions. These functions are PREFIX_reset, PREFIX_self_test, PREFIX_revision_query, PREFIX_error_query, and PREFIX_error_message.

Using Arrays As Parameters The VXIplug&play specification states that the caller must allocate space for an array or text parameter. This means that VEE must allocate the array before passing it as a parameter to the VXIplug&play function, as shown in this example.

Using the Close Function The close function PREFIX_close has one input parameter and no output parameters. The input parameter is the handle returned from PREFIX_init. Executing PREFIX_close takes the instrument off-line and clears any data associated with the instrument handle. There may also be some other driver-specific actions related to closing the instrument. The handle cannot be used again by instrument functions. The PREFIX_init routine must be called again to obtain a new handle.

Deleting the Library

After you finish using the VXIplug&play driver, the Delete Library object needs to be invoked for each driver loaded. After the library is unloaded, the library must be loaded again using the Import Library object before any functions using that library can be called.

A Simple Example

Here is an example program using a VXIplug&play driver in VEE. This program imports the library, initializes the device, closes the device, and deletes the library. (Each program thread is started independently with a Start button.)

A More Complete Example

The following figure shows a more complete example program that uses a VXIplug&play driver and allocates an array to be used as an output parameter.

Some Helpful Hints

Keeping Track of Handles The handle returned by PREFIX_init must be used by successive driver functions. There are two ways to accomplish this:

• Connecting Pins

The value of a handle can be passed by connecting the PREFIX_init routine data output pin to the vi data input pins on each function.

• Keeping Track of Handles Globally

The handle can be kept as a global variable. The handle from PREFIX_init routine is connected to a Set Global object. Each function that uses this handle, takes it from a Get Global object.

Control Flow The driver needs to perform actions in a certain sequence (initialization, calling functions, and closing). The VEE program must be written to ensure that the handle is valid for all functions that require its usage.


Using the To/From VXIplug&play Object

After you have added VXIplug&play instruments to the VEE instrument configuration, you can use the VXIplug&play drivers in your program. Access the instruments by the functions contained in the drivers. The To/From VXIplug&play object provides access to the VXIplug&play function panels.

To get the To/From VXIplug&play object:

Select I/O [image] Instrument Manager. The Instrument Manager appears and displays all currently configured VXIplug&play instruments (as well as any other instruments that are configured).

Select the instrument with which you want to communicate, and click the Plug&play Driver button. The outline of the object appears.

Place the outline of the To/From VXIplug&play object where you want it in the work area and click the mouse button. The object appears as follows.

Selecting a Function

Select the VXIplug&play functions from the To/From VXIplug&play object.

1. Double-click an empty transaction or select Add Trans or Insert Trans from the object menu. The Select a Function Panel dialog box appears. It displays function panels grouped into logical categories, such as Measure or Configure. Each driver has different categories.

• Click the [+] icons to view the hierarchical structure of function panels.

• Click the [-] icons to hide the function panels in the hierarchical structure.

• Click the [f(x)] icons to select the function panel. You will see a short description of the function panel in the lower part of the dialog box.

To completely expand a branch of the tree, select the item to expand and press the * key.

Generally, you will see only function panels that adhere to the VXIplug&play version 3.x specification and are allowed by VEE.

note

VEE automatically calls init() at the appropriate time. However, there may be other initialization functions, such as init_all(), init_next(), or init_first() in the list. These functions are not defined in the VXIplug&play specification and are not supported by VEE.

Do not select these functions. If you must use these functions, you need to create your program differently and call the VXIplug&play driver from a Call object as described in “Using VXIplug&play Functions from Call Objects"

There are no entries for PREFIX_init() or PREFIX_close().
These functions are performed automatically by VEE.

2 Click OK on the Select a Function Panel dialog box.

3 You see a tabbed dialog box called Edit a Function Panel that allows you to specify the parameters for the function panel.

Editing Function Panel Parameters

The Edit a Function Panel dialog box allows you to set controls and variables to pass to the selected VXIplug&play driver's function. There are two tabs, Panel and Configuration.

The Panel Tab. The Panel tab allows you to specify the constant (control) values to pass to the function.

• Controls - The top part of this dialog box contains controls to specify constant parameters. The names of the controls are labels specified from the function panel file.

• vi - Displays the unique "virtual instrument" handle (also called the "session handle") of the instrument. Depending on the driver version, the name of this field may change, but the location is always in the lower-left corner of the function panel.

• Error - Displays a non-zero value if an error occurred when executing this function panel. Depending on the driver version, the name of this field may change, but the location is always in the lower-right corner of the function panel.

• Function call - At the bottom of the dialog box is the C function and the parameters that are sent to the driver when the object executes. This command string is also shown as a transaction on the open view of the object.

Getting Help on a VXIplug&play Function Panel

In the Edit Function Panel dialog box, click the right mouse button on the background of the Panel tab for help on the function panel. A dialog box containing a description of the function appears.

Click the right mouse button on a control (not the label) for an explanation of the parameter.

For complete help on the VXIplug&play driver, select Instrument Help from the object menu of the To/From VXIplug&play object.

The Configuration Tab

The Configuration tab, allows you to specify the variables to pass to the function. This allows you to set the parameter values programmatically.

Parameter values are shown in groups. The name of each group is the label name of the parameter as specified in the VXIplug&play function panel. Function and reading are labels. Each group may contain the following information.

• Parameter Type - This provides information about the parameter data type and whether the parameter is Input Only, Input/Output, or Output Only.

• Parameter Value - When Constant is selected, this parameter is passed as a constant value that is set on the Panel tab. When Variable is selected, this parameter is passed as a variable. The value of the parameter may be changed programmatically. Some fields are always variables, such as the output for a reading.

Name - When the Parameter Type is set to Variable, this field is editable. By default, the name of the variable is set to its label name (or a similar name to make it a valid VEE variable name). You can change this to any valid variable name in VEE. If the variable is an input variable, you can also put an expression, function call, or global variable in this edit field.

Create Terminal - When the Parameter Type is set to Variable, this field is editable. When the check box is checked and Name does not currently exist as a terminal name, pressing OK creates the terminal (with the name specified in Name) as an input, output, or input/output terminal, as indicated in the dialog box. To delete a terminal once it is created, you must use Delete Terminal from the object menu

If the Name is changed and Create Terminal is checked, a new terminal is added.

If the Name is set to an invalid terminal name, Create Terminal is grayed out.

• Auto-Allocate Input - This appears on Input/Output parameters that have been set to Variable, not Constant. The next section provides more information.

Press the NOP button to save the latest settings shown in this dialog box and make this transaction a "no operation". This is the same as commenting out a line of code in a text-based computer program.

Press the Help button for help about the To/From VXIplug&play object. Press the OK button when you have finished editing.

Press the Instr Help button to get instrument-specific help written by the driver developer.

The Auto-Allocate Feature (Passing Arrays and Strings)

Some VXIplug&play functions want to return data in an array or Text string. The VXIplug&play specification requires that the application (VEE) allocate the memory for the array or string since the VXIplug&play function cannot pass back allocated memory. VEE must allocate the memory, and the function can write to that memory.

The Auto-Allocate feature lets you easily tell VEE how much memory to allocate. VEE allocates the correct data type and shape, in the size required.

If a parameter to a function is a variable that requires an array or a Text string, the Parameters tab displays an additional field: Auto-Allocate input. For example, in the following dialog box, readings can input an array. The Parameters tab shows Auto-Allocate input selected:

When Auto-Allocate input is selected, the Size field becomes active. The default size is 5000, but you can enter any appropriate size to allocate the input data. You must determine how large an array or string needs to be passed. An input terminal is not created for this parameter and VEE automatically allocates the memory for the parameter.

For an array, Size denotes the number of elements in the array. For a text string, Size denotes the number of characters (bytes). See Instrument Help or click the right mouse button on the Panel background or on the parameter for more information on the size of array or string the function requires.

note

If you use the Auto-Allocate input feature, a data input terminal is not created for the function. If the data input terminal already exists, you should delete it from the To/From VXIplug&play object.

If you do not select ("check") Auto-Allocate input, both input and output terminals are created for the function by default. You must create an object to allocate the correct type, shape, and amount of memory and connect it to the input terminal. See Passing Parameters for information on how to manually allocate the memory needed for inputs.

Be sure to allocate enough memory for all the values the function wants to return. If insufficient memory is allocated, this action will overwrite memory and cause a General Protection Fault or Segmentation Violation. Since the VXIplug&play DLL is linked directly into VEE, this situation can cause VEE to crash and exit.

Getting Help on a VXIplug&play Driver

From the object menu of the To/From VXIplug&play object, select Instrument Help to access the help file provided by the instrument manufacturer. This help topic contains information about using the VXIplug&play driver including the data types required for the parameters.

For help on each particular function, see Getting Help on a VXIplug&play Function Panel.


Introduction to Panel Drivers and Component Drivers

Panel Driver and Component Driver objects can be used for a particular instrument only if there is a driver file to support that instrument. The installation procedure for VEE allows you to select which drivers you want to install. For further information about how to select and configure the proper driver files for your instruments, see Configuring Instruments under Help [image] Tell Me About .... Also, the I/O libraries must be installed.

Panel Drivers

Panel Drivers serve two purposes in VEE:

• They allow you to define a measurement state that specifies all the instrument function settings. When a Panel Driver operates, the corresponding physical instrument is automatically programmed to match the settings defined in the Panel Driver.

• They act as instrument control panels for interactively controlling instruments. This is useful during development and debugging of your programs. It is also useful when your instruments do not have a physical front panel.

As shown in this figure the open-view of a Panel Driver contains a graphical control panel for the associated physical instrument. If the physical instrument is properly connected to your computer, you can control the instrument by clicking the fields in the graphical control panel. You can also make measurements and display the results by clicking the numeric and XY displays.

Even if the instrument is not connected to your computer, you can still use the graphical panel to define a measurement state. In fact, this can be a benefit if you want to develop programs before instruments are purchased or while they are being used elsewhere.

For example, suppose you want to program an HP 3325B function generator to provide two different output signals:

1 A square wave with a frequency of 20 kHz and an amplitude of 20mV rms.

2 A sine wave with a frequency of 50 kHz and an amplitude of 50mV rms.

The following figure shows the two Panel Drivers that provide the desired signals.

Component Drivers

In an instrument driver, each instrument function and measured value is called a component. A component is like a variable inside the driver that records the function setting or measured value. Thus, a Component Driver is an object that reads or writes only the components you specify as input and output terminals. This is in contrast to a Panel Driver, which automatically writes values for many or all components.

Component Drivers are provided to help you improve the execution speed of your program. Speed is the only advantage they provide over Panel Drivers. The execution speed of a program is generally impacted most when an instrument control object is attached to an iterator object where it must operate many times. In these cases, it is common for only one or two components to be changing; this is exactly the situation Component Drivers are designed to handle.

The increase in execution speed provided by a Component Driver will vary considerably from one situation to another. The increase depends primarily on the particular driver file used. There is no easy way to predict the exact increase in execution speed.

For example, suppose you want to program the HP 3325B Function Generator to do the following:

1 Output a sine wave with an initial frequency of 10 kHz and an amplitude determined by operator input.

2 Sweep the frequency output from 10 kHz to 1 MHz using 5 steps per decade.

In this case, it makes sense to use a Panel Driver to perform the initial setup and a Component Driver to repeatedly set the output frequency. A program that does this is shown below.

Further Information

For information about how to configure VEE, see Configuring Instruments under Help [image] Tell Me About ... For further information about how to use the Panel Driver and Component Driver objects, see Inside Panel Drivers and Panel Driver Operation.

Support For Register-Based VXI Devices

When using the instrument control objects to directly address VXI devices on the VXI backplane, you need to know whether devices are message-based or register-based. VEE communicates with message-based devices by means of SCPI (Standard Commands for Programmable Instruments) messages.

VEE also provides Interpreted SCPI (I-SCPI) support for most Hewlett-Packard and Agilent register-based devices. I-SCPI drivers let you communicate with register-based devices as though they were message-based. This means that a VEE program can communicate with a register-based device using standard SCPI messages, provided there is an I-SCPI driver for that particular device. If no I-SCPI driver is available for a register-based device, VEE must communicate with that device by directly accessing its registers.

The I-SCPI drivers give you the flexibility to use any of the instrument control objects you prefer. You can use the Panel Driver for easier programming, or use SCPI commands in Direct I/O for faster execution speed. When you program VEE to communicate with a register-based device using SCPI messages, VEE will inform you if the required I-SCPI driver is not available. In that case, you will need to access the device registers directly using Direct I/O or MultiInstrument Direct I/O.


Inside Panel Drivers

The VEE Panel Driver and Component Driver objects both require that the appropriate Panel Driver ("ID") be present, and that the instrument be configured to that driver. These instrument drivers are sometimes called "VEE drivers" or "Instrument Drivers". The Panel Driver file (the.cid file) must be present and configured to use Panel Driver and Component Driver objects. However, these files are not used for Direct I/O or VXIplug&play operations.

Panel Driver Files

Each Panel Driver describes the unique personality of a particular test instrument. A driver file is required to control any instrument using a Panel Driver and Component Driver object.

Panel Driver files (.cid files) are optionally copied onto your system disk when VEE is installed. Each driver file contains two basic types of information:

• A description of the instrument's functions and the commands used to set and query them.

• A description of the appearance and behavior of the graphical control panel visible in the open view of a Panel Driver object.

Components

Internally, Panel Driver and Component Driver objects represent each instrument function as a component. Component names are analogous to variable names in programming languages; components are used to hold the value of instrument function settings or measured values.

The following figure shows some of the components in the HP 3478A voltmeter.

Component Name | Instrument Function
ARRANGE | Autoranging is on or off
FUNCTION | The measurement function is voltage, current, or resistance.
TRIGGER | The trigger source is internal, external, fast, or single.
READING | The most recent measured value.

Access components interactively or through a program. To access a component interactively, click a labeled button or display in the open view of a Panel Driver. To access components using a graphical program, add them as input or output terminals. An example is shown below. For detailed procedures on using components, see “Selected Techniques" and “Using Component Driver Objects in a Program".

States

An instrument state is a specific set of values for all components in a particular driver. You set all the components in a voltmeter driver to particular values for AC voltage measurements. You use a different set of component values to measure DC current. These are two states for the voltmeter. This example shows two voltmeter states.

In VEE, each instance of a Panel Driver represents a separate measurement state. (Panel Driver objects are often called "state drivers".) It is common to have more than one Panel Driver in a program, where each Panel Driver programs the same physical instrument to a unique measurement state.

Each Panel Driver object you create using the same instrument Name communicates with the same physical instrument.

See Also

How Panel Driver-Based I/O Works, Panel Driver Operation, Selected Techniques


How Panel Driver-Based I/O Works

When you place a Panel Driver or Component Driver object in a program, VEE establishes a state record in memory. This state record is specific to a particular instrument Name. Names are discussed in greater detail in “The Importance of Names".

All driver-based objects that reference a particular Name share a single state record. The state record reflects the current values of each of the instrument's components. When you write to components using Panel Driver or Component Driver objects, VEE updates both the physical instrument and the state record.

If you write to the instrument using Direct I/O, VEE marks the state record as invalid because the state record no longer matches the true state of the physical instrument. However, subsequent use of a Panel Driver or Component Driver object causes VEE to recall the instrument's state, which resynchronizes the physical instrument state and state record.

Important differences occur when the Panel Driver and Component Driver objects operate.

See Also

Inside Panel Drivers, Panel Driver Operation, Selected Techniques


Panel Driver Operation

When a Panel Driver operates, it sends only those commands necessary to make the state of the physical instrument match the state defined in the graphical control panel.

If necessary, a Panel Driver sends commands to reset and update all settings in the corresponding physical instrument. This behavior is affected by the Incremental Mode setting described in Advanced Instrument Properties Dialog Box: Panel Driver Tab

If you set Incremental Mode to ON, VEE compares the current state record to the desired state defined in the Panel Driver and determines which components must be changed. VEE sends only those commands required to update the affected components.

If you set Incremental Mode to OFF, or if the current state record is marked as invalid, VEE explicitly sends commands to update each component in order to guarantee synchronization between the desired state and the state of the physical instrument.

A Panel Driver operates when its sequence input pin is activated or when you click one of the control panel buttons visible in the open view.

Component Driver Operation

When a Component Driver operates, it writes only to those components that appear as input terminals and reads only from those components that appear as output terminals. That is why Component Driver objects generally operate faster than Panel Driver objects. A Panel Driver potentially writes to many components to achieve a particular state; a Component Driver writes to only the components specified.

Components are read and written in the order they appear as terminals, from top to bottom. This order of operation is important in cases where you want the instrument to change the value of one component, based on the value of another. This interaction is called coupling. With component drivers you must do this manually.

Multiple Driver Objects

Some situations that can be confusing when using multiple objects that:

• Use the same instrument Name.

• Use the same instrument address.

• Use the same driver file.

The Importance of Names The Name field in the Instrument Properties dialog box logically maps each instrument object to the address of a physical instrument and the other configuration information. To determine the Name of an instrument object, click Show Config in the object menu. The text in the object title is not necessarily the same as the Name.

In general, only one configured Name should reference a particular physical instrument. Multiple Name references to the same instrument address causes unpredictable results in a program using Panel Driver objects. VEE's internal records of instrument states are organized by Names. Two Panel Driver objects with different names will blindly write to the same address, invalidating each other's state records.

In some cases involving Direct I/O, you may need more than one Name for the same physical instrument. This may be necessary if certain settings in the Direct I/O tab of the Advanced Instrument Properties dialog box need to be varied depending on the direct I/O operation.

For example, you may want to send some commands to an oscilloscope with EOI asserted on the last character of data and some commands without EOI. In this case, you can configure one instrument with the Name Scope_EOI and another instrument with the Name Scope. Both Scope and Scope_EOI have the same Address setting but different settings for END on EOL.

The configured Name appears as the default title in instrument objects when you select them from the menu. Editing the title in no way affects the relationship to the Name.

Names are also important for saving and opening programs containing instruments. When you save a program, the Name of each instrument object in the program is saved. When you open a program, VEE looks in the current I/O configuration for the Name of each instrument being loaded.

For example, if you saved a program containing a Direct I/O object with a name of My_Scope, there must be an instrument named My_Scope in the current I/O configuration. If the object under consideration is a Panel Driver or Component Driver, the ID Filename (driver file) in the current I/O configuration must match the one used in the saved program.

Names must match exactly, including spaces, except that Name is not case-sensitive.

Reusing Driver Files

It is valid (and not uncommon) to have several objects with different names that use the same driver file. For example, you might have a test system that uses three programmable power supplies named Supply1, Supply2, and Supply3 at three separate addresses that all use the hp665x.cid driver file. Since the Names are different, VEE maintains a separate state record for each name; a Panel Driver for Supply1 will have no effect on anything related to Supply2 or Supply3.

See Also

How Panel Driver-Based I/O Works, Inside Panel Drivers, Selected Techniques


Configuring for a Direct I/O Object

The following example shows how to configure a Direct I/O object. In this example, we configure a Serial Instrument at logical unit 1 (COM1) for direct I/O.

1 Select My Configuration

2 Click on Find Instruments

3 When Find Instruments is finished, highlight the newInstrument(@ASRL1::INSTR), then click Instrument Properties...

4 You should see the dialog box as follows.

The Instrument Properties dialog box allows you to change the name and address of the new instrument. Change the name to Serial1.

Click Advanced... to display the Advanced Instrument Properties dialog box. There are two tabs of interest.

The Serial tab allows you to specify the serial parameters such as baud rate. See “Details of the Properties Dialog Boxes" for further information about the individual parameters and fields. You can use the defaults for many applications.

The Direct I/O tab, shown below, allows you to specify a number of parameters for direct I/O, including the EOL sequence. You can use the defaults for most applications.

note

The selection of fields displayed by the Direct I/O tab depends on the Interface that you have selected. In addition, for VXI only, there are two additional tabs, A16 Space and A24/A32 Space.

These tabs allow you to configure a VXI device's registers for WRITE or READ transactions in a Direct I/O object. See “Details of the Properties Dialog Boxes" for further information about the parameters and fields displayed by each tab.

Click OK (or Cancel to make no changes) on each dialog box to return to the Instrument Manager. In this example, a new instrument, Serial1, has been configured under the ASRL1 interface. To add a Direct I/O object to the work area, click the Direct I/O button, place the object, and click again for the display below.

note

Direct I/O objects use transaction-based I/O to communicate with instruments, without using an instrument driver. See Using the Direct I/O Object.


Configuring for a VXIplug&play Driver

The procedure to configure for a To/From VXIplug&play object is very similar to the procedures for Direct I/O objects. However, you must first install the appropriate VXIplug&play driver files as described in Introduction to VXIplug&play.

note

If you are using the Windows operating system, the VISA Assistant utility provides helpful information about VXIplug&play drivers. The information helps you determine valid addresses required for VXIplug&play driver configuration. Look for VISA Assistant in the Windows Start menu Program Files [image] Agilent I/O Libraries [image] VISA Assistant

For example, we will add a VXIplug&play configuration for the ag33250a Function Generator. Select I/O [image] Instrument Manager, and click Add.... The Instrument Properties dialog box appears. Change the name to gpibDevice and select GPIB for the Interface type. Click in the VISA Address and enter the VISA address for the instrument. Here you may enter GPIB::22::INSTR.

Click Advanced... to display the Advanced Instrument Properties dialog box, and then select the Plug&play Driver tab.

Next, select the driver named AG33250A from the Plug&play Driver Name drop-down list. You will not be able to select the VXIplug&play driver unless you have previously installed the driver.

note

Only the Plug&play Driver tab applies to configuring VXIplug&play drivers. The General, Direct I/O, Panel Driver, A16 Space, and A24/A32 Space tabs have no effect on a VXIplug&play configuration. For example, the Live Mode setting on the General tab is ignored since a VXIplug&play device is always considered live.

When you have configured the instrument, click OK on each dialog box to return to the Instrument Manager, which will show the added instrument as follows.

Click the Plug&play Driver button to add a To/From VXIplug&play object.

See “Using the To/From VXIplug&play Object” for information about using the To/From VXIplug&play object.


Details of the Properties Dialog Boxes

This section provides a detailed description of the Instrument Properties dialog box, each tab of the Advanced Instrument Properties dialog box, and the Interface Properties dialog box.

Instrument Properties Dialog Box

The Instrument Properties dialog box appears when you select an instrument and click either the Add... button or the Properties button in the Instrument Manager. An example of this dialog box is shown below.

The following sections describe the individual fields.

Name Field

VEE Instrument control objects require that the Name field uniquely identifies a particular instrument configuration. The instrument Name is a symbolic link between each instance of an Instrument Control object and all the configuration information corresponding to that Name. Usually, this field is used to give a descriptive name to the instrument, such as Oscilloscope or Power_Supply.

Name must be a valid VEE variable name if you want to programmatically get/set its properties. The name must start with an alpha character, followed by alphanumeric characters or underscores.

Names must be unique. For example, you cannot configure two instruments with a Name of Scope. While it is possible to create two different Names that refer to the same physical instrument, it can cause problems if you use both Names with Panel Drivers or VXIplug&play drivers in the same program.

Do not confuse the Name of an instrument with the text that appears as the title in an Instrument Control object. The default title of an Instrument Control object is the name, but you can change the title and it has no effect on the Name. If you need to determine the Name of a particular instance of an Instrument Control object, select Properties in the Instrument Control object menu, (e.g. Direct I/O, MultiInstrument I/O).

note

It is very important that you use Names correctly. This section discusses only the more common situations. For more details about how VEE uses names, see The Importance of Names.

Refer to Instrument Properties for detailed information about Board Number, VISA Alias, VISA Address, and Advanced.. fields.

See Also

Advanced Instrument Properties dialog box, Logical Units and I/O Addressing, LAN Gateways


Advanced Instrument Properties Dialog Box: General Tab

The following figure shows an example of the General tab of the Advanced Instrument Properties dialog box:

The following sections describe the individual fields.

note

The parameters specified in the General tab apply to Direct I/O, Panel Driver, and Component Driver objects, but not to To/From VXIplug&play objects.

Timeout (sec) Field

The Timeout field specifies how many seconds VEE will wait for an instrument to respond to a request for communication before generating an error. The default value of five seconds works well for most applications.

In general, you should not set this field to 0. If you do, VEE will never detect a timeout. Certain Direct I/O transactions for register or memory access of VXI devices do not support a timeout.

Live Mode Field

The Live Mode field determines whether or not VEE will attempt to communicate with an instrument at the specified address. To communicate with an instrument connected to your computer, you must set Live Mode to ON.

If Live Mode is OFF for a particular instrument, you can run programs containing Panel Drivers, Component Drivers, or Direct I/O objects that would otherwise read and write to that instrument. However, no instrument communication actually takes place. This behavior can be useful if you want to develop or debug portions of a program while instruments are not available.

Byte Ordering Field

Use this field to specify the order the device uses for reading and writing binary data. VEE uses the value in this field to determine if byte swapping is necessary. Click this field to choose between MSB (send Most-Significant Byte first) and LSB (send Least-Significant Byte first). All IEEE 488.2-compliant devices must default to MSB order. See your device manual for specific information.

Description (optional) Field

The Description field is typically used to record the manufacturer's model number. For example, the Description for the HP 54504A oscilloscope could be hp54504a. This field is provided for your convenience, but VEE does not use it.


Advanced Instrument Properties Dialog Box: Direct I/O Tab

The following figure shows an example of the Direct I/O tab of the Advanced Instrument Properties dialog box (shown for the GPIB Interface):

The following sections describe the individual fields.

note

When addressing VXI devices directly on the VXI backplane, you can use SCPI messages to control register-based devices, if I-SCPI drivers exist for them. VEE will inform you if required I-SCPI drivers are not available.

If I-SCPI drivers are not available, you must control register-based devices by direct read/write access to device registers or device memory. See “Advanced Instrument Properties Dialog Box: A16 Space (VXI Only) Tab" or “Advanced Instrument Properties Dialog Box: A24/A32 Space (VXI Only) Tab" for details.

Read Terminator Field

The Read Terminator field specifies the character that terminates READ transactions. The entry in this field must be a single character surrounded by double quotes. "Double quote" means ASCII 34 decimal. VEE recognizes any ASCII character as a Read Terminator as well as the escape characters shown in the following table.

The character you should specify is determined by the design of your instrument. Most GPIB instruments send Newline after sending data to the computer. See your instrument programming manual for details.

Escape Character | ASCII Code (decimal) | Meaning
\n | 10 | Newline
\t | 9 | Horizontal Tab
\v | 11 | Vertical Tab
\b | 8 | Backspace
\r | 13 | Carriage Return
\f | 12 | Form Feed
\" | 34 | Double Quote
\' | 39 | Single Quote
\\ | 92 | Backslash
\ddd |  | The ASCII character corresponding to the three-digit octal value ddd.

Write EOL Sequence Field

The EOL Sequence field specifies the characters that are sent at the end of WRITE transactions that use EOL ON. The entry in this field must be zero or more characters surrounded by double quotes. "Double quote" means ASCII 34 decimal. VEE recognizes any ASCII characters within EOL Sequence including the escape characters shown in above table.

Write Multi-field As Field

The Multi-field As field specifies the formatting style for multi-field data types for WRITE TEXT transactions. The multi-field data types in VEE are Coord, Complex, PComplex, and Spectrum. Other data types and other formats are not affected by this setting.

Specifying a multi-field format of (...) Syntax surrounds each multi-field item with parentheses. Specifying Data Only omits the parentheses, but retains the separating comma. For example, the complex number 2+2j could be written as (2,2) using (...) Syntax or as 2,2 using Data Only syntax.

Write Array Separator Field

The Array Separator field specifies the character string used to separate elements of an array written by WRITE TEXT transactions. The entry in this field must be a single character surrounded by double quotes. "Double quotes" means ASCII 34 decimal. VEE recognizes any ASCII character as an Array Separator as well as the escape characters shown in above table.

WRITE TEXT STR transactions in Direct I/O objects that write arrays are a special case. In this case, the value in the Array Separator field is ignored and the linefeed character (ASCII 10 decimal) is used to separate the elements of an array. This behavior is consistent with the needs of most instruments.

VEE allows arrays of multi-field data types. For example, you can create an array of Complex data. In this case, if Multi-Field Format is set to (...) Syntax the array will be written as:

   (1,1)array_sep(2,2)array_sep ...

where array_sep is the character specified in the Array Separator field.

Write Array Format Field

The Array Format field determines the manner in which multidimensional arrays are written. For example, mathematicians write a matrix like this:

   1 2 3 4 5 6 7 8 9

VEE writes the same matrix in one of two ways, depending on the setting of Array Format. In the two examples that follow, EOL Sequence is set to "\n" (newline) and Array Separator is set to " " (space).

   1 2 3 Block Array Format

   4 5 6

   7 8 9

1 2 3 4 5 6 7 8 9 Linear Array Format

Either array format separates each element of the array with the Array Separator character. Block Array Format takes the additional step of separating each row in the array using the EOL Sequence character.

In the more general case (arrays greater than two dimensions), Block Array Format outputs an EOL Sequence character each time a subscript other than the right-most subscript changes. For example, if you write the three-dimensional array A[x,y,z] using Block array format with this transaction:

   WRITE TEXT A

an EOL Sequence will be output each time x or y changes value. If the size of each dimension in A is two, the elements will be written in this order:

   A[0,0,0] A[0,0,1]<EOL Sequence>

A[0,1,0] A[0,1,1]<EOL Sequence>

<EOL Sequence>

A[1,0,0] A[1,0,1]<EOL Sequence>

A[1,1,0] A[1,1,1]<EOL Sequence>

Notice that after A[0,1,1] is written, x and y change simultaneously and consequently two <EOL Sequence>s are written.

Write END (EOI) On EOL Field (GPIB Only)

END on EOL controls the behavior of EOI (End Or Identify). If END on EOL is YES, the EOI line is asserted on the bus at the time the last data byte is written under one of the following circumstances:

1 A WRITE transaction with EOL ON executes.

2 A WRITE transaction executes as the last transaction listed in the Direct I/O object.

3 One or more WRITE transactions execute without asserting EOI and are followed by a non-WRITE transaction, such as READ.

Many instruments accept either EOI or a newline as valid message terminators. Some block transfers may require EOI. See your instrument's programming manual for details.

Conformance Field

Conformance specifies whether an instrument conforms to the IEEE 488.1 or IEEE 488.2 standard. See your instrument programming manual to determine the standard to which your instrument conforms, and then set the Conformance field accordingly.

Each of these standards defines communication protocols for the GPIB Interface. However, IEEE 488.2 specifies rules for block headers and learn strings that are left undefined in IEEE 488.1. All message-based VXI instruments are IEEE 488.2 compliant, as well as register-based VXI instruments supported by I-SCPI drivers.

If you set Conformance to IEEE 488 (which denotes IEEE 488.1), you may optionally specify additional settings to handle block headers and learn strings, as described in the following sections.

Binblock Field

The Binblock field specifies the block data format used for WRITE BINBLOCK transactions. Binblock may specify IEEE 728 #A, #T, or #I block headers. If Binblock is None, WRITE BINBLOCK writes an IEEE 488.2 Definite Length Arbitrary Block Response Data block.

IEEE 728 block headers are of the following forms:

#A<Byte_Count><Data>

#T<Byte_Count><Data>

#I<Data><END>

where:

<Byte_Count> is a 16-bit unsigned integer that specifies the number of bytes that follow in <Data>.

<Data> is a stream of arbitrary bytes.

<END> indicates that EOI is asserted with the last data byte transmitted.

State (Learn String) Field

The State field indicates whether or not the instrument has been configured for uploading and downloading learn strings. If the State entry is Not Config'd and you want to configure the instrument for use with learn strings, click the State field and the Upload String and Download fields will appear. If the State entry is Not Config'd, the Upload String and Download String fields are set to the null string.

Upload String Field

The Upload String field specifies the command that is sent to the instrument when you select Upload State from the Direct I/O object menu. Specify the command that causes the instrument to output its learn string. See your instrument programming manual for details. You must surround the command with double quotes.

Download String Field

The Download String field specifies the string that is sent to the instrument immediately before the learn string as the result of a WRITE STATE transaction in a Direct I/O object. This field is provided to support instruments that require a command prefix when downloading a learn string. See your instrument programming manual for details.


Advanced Instrument Properties Dialog Box: Plug&play Driver Tab

The following figure shows an example of the Plug&play Driver tab of the Advanced Instrument Properties dialog box (shown for the GPIB Interface):

The Plug&play Driver tab is the only tab of the Advanced Instrument Properties dialog box that applies to VXIplug&play driver configurations.

The following sections describe the individual fields.

Plug&play Driver Name Field

This field specifies the name of the VXIplug&play driver. You must select a driver name, as this parameter is required. The drop-down list displays all VXIplug&play drivers installed. If there are no entries in the list, either you do not have any VXIplug&play drivers installed or your registry entry or the environment variable may not be set correctly.

Parameters to init() call Field

Address

Enter the address that identifies the instrument. The address format depends on the interface to which the instrument is connected:

  • VXI address string (embedded VXI, VXLink, or MXIbus controller).

    For a VXI instrument with an embedded, VXLink, or MXIbus controller, the address string takes the form

    VXI[board]::VXI logical address[::INSTR]

    An example is VXI::24::INSTR for an instrument at logical address 24.

    The board number is optional for the first board (VXI::24::INSTR is equivalent to VXI0::24::INSTR). However, the board number is required for subsequent boards (VXI1, VXI2, and so forth).

  • GPIB-VXI address string (command module).

    For a VXI instrument that is being controlled from a GPIB card connected to a command module, the address string takes the form

    GPIB-VXI[board]::VXI logical address [::INSTR]

    An example is GPIB-VXI::24::INSTR (or GPIB-VXI0::24::INSTR) for an instrument at VXI logical address 24.

  • GPIB address string (GPIB instruments).

    For a non-VXI instrument being controlled from a GPIB card, the address string takes the form

    GPIB[board]::GPIB primary address::[GPIB secondary address][::INSTR]

    An example is GPIB::23::INSTR (or GPIB0::23::INSTR) for a GPIB instrument at primary address 23. (The optional secondary address is rarely used.)

Perform Identification Query

Select this check box if you want the driver to query the instrument for its identification the first time a function panel for this driver is executed. You generally want to select the check box, except in the rare case that your instrument does not support this operation.

Perform Reset

Select this check box if you want a reset sent to the instrument the first time a function panel for this driver is executed. You generally want to select the check box, except in the rare case that your instrument does not support this operation. Note that all VXI instruments support this operation.

Download Drivers

If you need a new driver or to update a driver, click on the URL in the Advanced Instrument Properties dialog box.


Advanced Instrument Properties Dialog Box: Panel Driver Tab

The following figure is an example of the Panel Driver tab of the Advanced Instrument Properties dialog box:

note

You can configure register-based VXI devices as message-based only if they are supported by I-SCPI drivers.

This tab is used to configure both Panel Driver and Component Driver objects. The following sections describe the individual fields.

ID Filename Field

The ID Filename field specifies the file that contains the desired Panel Driver. Click the field to display the Read from what Instrument Driver? dialog box and choose a file. Files are named according to instrument model number.

Be certain to choose the name corresponding to the exact model number you are using, as there are similar file names such as hp3325a.cid and hp3325b.cid.

Sub Address Field

The Sub Address field specifies the subaddress used by certain drivers to identify plug-in modules in cardcage-type instruments, such as data acquisition systems and switches. If you are not configuring a driver for one of these plug-ins, set this field to "" (the NULL string).

note

Since very few drivers use subaddresses, the default setting of "" (the NULL string) is the proper setting in almost all situations.

If you are configuring a driver for one of these plug-ins, see online help for the instrument driver to determine if and how subaddresses are used.

note

Do not confuse the Sub Address field with a secondary address for GPIB instruments. Subaddresses are part of the driver configuration; they are not part of the hardware address.

Error Checking Field

The Error Checking field determines whether or not VEE queries the instrument for errors after setting component values. Set this field to ON unless execution speed is not acceptable.

Incremental Mode Field

The Incremental Mode field specifies whether or not incremental state recall is used with Panel Driver objects.

note

The proper setting for Incremental Mode is ON in almost all situations.

When Incremental Mode is set to ON, VEE automatically minimizes the number of commands sent to the instrument to change its state. To do this, VEE compares its record of the current state the physical instrument to the new state specified in the Panel Driver.

VEE determines which component settings are different and then sends only those commands needed to change components that do not match the desired state. In most cases, you should set Incremental Mode to ON, since this mode provides the best execution speed.

When Incremental Mode is set to OFF, VEE explicitly sets the values of every component when a corresponding Panel Driver operates. This mode is generally used only when there is a chance that VEE's record of the instrument state does not match the true state of the instrument.

The Incremental Mode setting affects the operation of Panel Driver objects, but not Component Driver objects. These things do suggest setting Incremental Mode to OFF:

• Allowing front panel operation of an instrument while a VEE program is also controlling the instrument.

• Changing instrument settings outside of the VEE environment through C programs or shell commands while a VEE program is also controlling the instrument.

Using combinations of Component Drivers, Panel Drivers, and Direct I/O objects in a program does not imply that you need to set Incremental Mode to OFF.


Advanced Instrument Properties Dialog Box: Serial Tab

The following figure is an example of the Serial tab of the Advanced Instrument Properties dialog box (valid for serial interfaces only):

You can set the following fields for the serial (RS-232) interface:

• Baud Rate – The default is 9600 (bits per second).

• Character Size – The default is 8 (bits). Allowed values are 5, 6, 7, 8, and None.

• Stop Bits – The default is 1. Allowed values are 1 and 2.

• Parity – The default is None. Allowed values are None, Odd, Even, Mark, and Space.

• Handshake – The default is None. Allowed values are None and Xon/Xoff.

• Receive Buffer Size – The default is 4096 (bytes).


Advanced Instrument Properties Dialog Box: GPIO Tab

The following figure is an example of the GPIO tab of the Advanced Instrument Properties dialog box (valid for GPIO interfaces only):

The GPIO tab has only one field, Data Width. The Data Width field specifies the number of bits of parallel data transmitted as a unit across the GPIO interface. This field configures the interface to read and write data eight or sixteen bits wide. No hardware switches need to be set in conjunction with this field.


Advanced Instrument Properties Dialog Box: A16 Space (VXI Only) Tab

The following figure is an example of the A16 Space tab of the Advanced Instrument Properties dialog box. This tab appears only for the VXI Interface, and is used only for register-based Direct I/O transactions.

The following sections describe the individual fields.

Byte Access (D8) Field

The Byte Access field specifies whether the VXI device supports 8-bit A16 memory accesses. The possible choices for this field are:

• NONE - Device does not support byte access.

• ODD ACCESS - Device supports byte access, but only on odd byte boundaries (D08(O)).

• ODD/EVEN ACCESS - Device supports byte access on all boundaries (D08(EO)).

Word Access (D16) Field

The Word Access field is not editable. All VXI devices must support 16-bit access (D16).

LongWord Access (D32) Field

The LongWord Access field specifies whether the VXI device supports 32-bit A16 memory accesses. The possible choices are:

• NONE - Device does not support 32-bit access.

• D32 ACCESS - Device supports 32-bit A16 memory access.

Add Register Field

When you click the Add Register field, it adds a row of fields to the dialog box. These fields allow you to configure access to a device's A16 memory. The four fields are:

• Name - The symbolic name of the register, which is used to refer to the particular register in a Direct I/O object using READ REGISTER or WRITE REGISTER transactions.

• Offset - The offset in bytes from the relative base of a device's A16 memory for the register being configured.

• Format - The data format that will be read from, or written to, the register being configured. The read or write access will take place at the byte specified in the Offset field. The possible formats are:

• BYTE - Read or write a byte. The device must support and be configured correctly for 8-bit access by using the BYTE field discussed above. If the BYTE field is ODD, the byte location specified in the Offset field must be an odd number.

• WORD16 - Read or write a 16-bit word. The 16-bits are represented as a two's complement integer. All VXI devices explicitly support this format.

• WORD32 - Read or write a 32-bit word. The 32-bits are represented as a two's complement integer. VEE supports this format even if the LongWord Access field is specified as NONE (by using two D16 accesses to read or write all 32 bits). If the LongWord Access field is specified as D32 ACCESS, all 32 bits are accessed.

• REAL32 - Read or write a 32-bit word. The 32-bits are represented as a IEEE 754 32-bit floating-point number. VEE supports this format even if the LongWord Access field is specified as NONE (by using two D16 accesses to read or write all 32 bits). If the LongWord Access field is specified as D32 ACCESS, all 32 bits are accessed.

• Mode - Specifies what I/O mode the register will support. The choices are:

• READ - This register will appear as a choice in a READ REGISTER transaction only.

• WRITE - This register will appear as a choice in a WRITE REGISTER transaction only.

• READ/WRITE - This register will appear as a choice in both a READ REGISTER and WRITE REGISTER transaction.

Delete Register Field

When you click the Delete Register field, it will display a list of the symbolic names of the currently configured registers. The selected register will be removed from the dialog box.

An Example

The following figure shows the A16 Space tab with the register configuration of an HP E1411B VXI Multimeter. Note that the list of registers scrolls as additional registers are added using Add Register.

note

An extended (A24/A32 Space) memory configuration would be similar, but would consist of memory "locations," rather than"registers."

The Offset field is configured with the offset in bytes of each register from the relative base of the device's A16 space. The status register (Name: = stat in the figure) is configured with a 4-byte offset and is configured for READ mode.

The control register is not shown in the figure, but typically would be configured for a 4-byte offset in WRITE mode. While two separate register locations could have the same mode, the Name field must be unique. However, it would be possible for the register at byte location 4 to be named statuscontrol with a mode of READ/WRITE.


Advanced Instrument Properties Dialog Box: A24/A32 Space (VXI Only) Tab

The following figure is an example of the A24/A32 Space tab of the Advanced Instrument Properties dialog box. This tab appears only for the VXI Interface, and is used only for register-based Direct I/O transactions.

The following sections describe the individual fields.

note

The term "extended memory" indicates either A24 or A32 memory in a VXI device. (A VXI device can implement either A24 or A32 memory, but not both.)

Byte Access (D8) Field

The Byte Access field specifies whether the VXI device supports 8-bit memory accesses. The possible choices for this field are:

• NONE - Device does not support byte access.

• ODD ACCESS - Device supports byte access, but only on odd byte boundaries (D08(O)).

• ODD/EVEN ACCESS - Device supports byte access on all boundaries (D08(EO)).

Word Access (D16) Field

The Word Access field is not editable. All VXI devices must support 16-bit access (D16) for all memory spaces.

LongWord Access (D32) Field

The LongWord Access field specifies whether the VXI device supports 32-bit memory accesses. The possible choices are:

• NONE - Device does not support 32-bit access.

• D32 ACCESS - Device supports 32-bit A16 memory access.

QuadWord Access (D64) Field

The QuadWord Access field specifies whether the VXI device supports 64-bit extended memory access. The possible choices are:

• NONE - Device does not support 64-bit access.

• D64 ACCESS - Device supports 64-bit memory access.

Agilent I/O Libraries G.02.02 supports 64-bit access to some VXI I/O instruments’ memory space. This feature enables VEE programs to read/write memory in 64-bit units for VXI instruments that support this mode. If you have version G.02.02 installed, you can use the A24/A32 Space Tab on the Advanced Instrument Configuration dialog box to enable this access mode.

To enable this mode, first enable QuadWord access (D64) Access and choose format WORD32*2, or REAL64. If you choose the WORD32*2 format, a 64-bit value is read into two adjacent numbers of the INT32 array.

Location: I/O [image] Instrument Manager [image] (select VXI instrument) [image] Edit Instrument [image] Advanced I/O Config... A24/A32 Space Tab.

Add Location Field

When you click the Add Location field, it adds a row of fields to the dialog box. These fields allow you to configure access to a device's extended memory. The four fields are:

• Name - The symbolic name of the location, which is used to refer to the particular memory location in a Direct I/O object using READ MEMORY or WRITE MEMORY transactions.

• Offset - The offset in bytes from the relative base of a device's extended memory for the location being configured.

• Format - The data format that will be read from, or written to, the location being configured. The read or write access will take place at the byte specified in the Offset field. The possible formats are:

• BYTE - Read or write a byte. The device must support and be configured correctly for 8-bit access by using the BYTE field discussed above. If the BYTE field is ODD, the byte location specified in the Offset field must be an odd number.

• WORD16 - Read or write a 16-bit word. The 16-bits are represented as a two's complement integer. All VXI devices explicitly support this format.

• WORD32 - Read or write a 32-bit word. The 32-bits are represented as a two's complement integer. VEE supports this format even if the LongWord Access field is specified as NONE (by using two D16 accesses to read or write all 32 bits). If the LongWord Access field is specified as D32 ACCESS, all 32 bits are accessed.

• REAL32 - Read or write a 32-bit word. The 32-bits are represented as a IEEE 754 32-bit floating-point number. VEE supports this format even if the LongWord Access field is specified as NONE (by using two D16 accesses to read or write all 32 bits). If the LongWord Access field is specified as D32 ACCESS, all 32 bits are accessed.

• WORD32*2 - Read or write a 64-bit word as two 32-bit words (as two Int32). QuadWord Access must be enabled.

• REAL64 - Read or write a 64-bit word as a REAL64. QuadWord Access must be enabled.

• Mode - Specify what I/O mode the location will support. The choices are:

• READ - This location will appear as a choice in a READ MEMORY transaction only.

• WRITE - This location will appear as a choice in a WRITE MEMORY transaction only.

READ/WRITE - This location will appear as a choice in both a READ MEMORY and WRITE MEMORY transaction.

Delete Location Field

When you click the Delete Location field, it will display a list of the symbolic names of the currently configured location. The selected location will be removed from the dialog box.


Understanding I/O Transactions

I/O transactions are used by VEE to communicate with instruments, files, strings, the operating system, interfaces, other programs, and printers. For example, look at the To File object below.

This To File object sends data to the specified file myFile. It can include inputs, called transactions, to accept data from a program. For example, this To File object includes the transaction WRITE TEXT a EOL. When you double-click the transaction, an I/O Transaction dialog box appears, which configures the specific transaction statement.

There are different forms of this dialog box depending on the object, but all contain certain common elements, including the “actions”, the “encoding”, the “expression list”, the “format”, and the “end-of-line” (EOL) sequence.


I/O Transaction Format

An I/O transaction to write data is usually in the following format:

<action> <encoding> <expression list> <format> <EOL>

Follows are the most common actions: READ, WRITE, EXECUTE, and WAIT.

Action | Description
READ | Reads data from the specified source using the specified encoding and format.
WRITE | Writes data to the specified target using the specified encoding and format.
EXECUTE | Executes a specific command. For example, EXECUTE REWIND repositions a file read or write pointer to the beginning of the file without erasing the contents. EXECUTE CLOSE closes an open file.
WAIT | Waits the specified number of seconds before the next transaction.

note

There are also a number of actions for I/O [image] Advanced I/O Operations that you can examine by exploring the objects in the menu.

Encodings and formats refer to the way data is packaged and sent. For instance, a TEXT encoding sends data as ASCII characters. The TEXT encoding could be formatted in a number of ways. For example, to send a string of letters and numbers to a file, a WRITE TEXT STRING transaction would send the entire string represented by ASCII characters. A WRITE TEXT REAL transaction would only extract the Real numbers from the same string and send them using ASCII characters for the individual digits. Follows are the brief explanations of encodings.

Encoding | Explanations
TEXT | Reads or writes all data types in a human-readable form (ASCII) that can easily be edited or ported to other software applications. VEE numeric data is automatically converted to text.
BYTE | Converts numeric data to binary integer and sends or receives the least significant byte.
CASE | Maps an enumerated value or an integer to a string and reads/writes that string. For example, you could use CASE to accept error numbers and write error messages.
BINARY | Handles all data types in a machine-specific binary format.
BINBLOCK | Uses IEEE488.2 definite length block headers with all VEE data types in binary files.
CONTAINER | Uses VEE specific text format with all data types.

In a write transaction, an “expression list” is simply a comma-separated list of expressions that need to be evaluated to yield the data sent. The expression may be composed of a mathematical expression, a data input terminal name, a string constant, a VEE function, a UserFunction, or a global variable. In a read transaction, the expression list should consist of a comma-separated list of output terminal names that indicate where to store the data when it is read.

In conjunction with reading data from instruments, data formats are described in the “How to Control Instruments,” . Most of these formats apply to all I/O transactions.

EOL (end-of-line sequence of characters) may be turned on or off, and you can specify the EOL sequence by opening the object menu of most of the I/O [image] To objects and selecting Properties..., then select Data Format, and make the changes under Separator Sequence.


Creating and Reading Transactions

All I/O objects discussed here contain transactions. A transaction specifies a low-level input or output operation, such as how to read or write data. Each transaction appears as a line of text listed in the open view of an I/O object. To view a typical transaction, click I/O [image] To [image] String to create a To String object.

To add a transaction, double click in the object.

The following figure is a simple program using the To String object to illustrate how transactions operate. The program uses two transactions, one to write a string literal and one to write a number in fixed decimal format.

You generally need to do at least two things with a transaction-based object:

1 Add additional transactions as required.

2 Add input terminals, output terminals, or both. Most terminals will be automatically added as needed—as you add or edit transactions.

See Also

Creating and Editing Transactions, Adding Terminals, Reading Transaction Data, Suggestions for Developing Transactions


Creating and Editing Transactions

To Edit Transactions

Editing with Mouse and Keyboard

This table describes briefly how to edit transactions with a mouse.

To Do This... | Click This...
Add another transaction to the end of the list. | Double click in the object or add Trans in the object menu.
Move the highlight bar to a different transaction. | Any non-highlighted transaction.
Insert a transaction above the highlighted transaction. | Insert Trans in the object menu.
Cut (delete) the highlighted transaction, saving it in the transaction “cut-and-pasteEbuffer. | Cut Trans in the object menu.
Copy the highlighted transaction to the transaction “cut-and-pasteEbuffer. | Copy Trans in the object menu.
Paste the transaction currently in the buffer above the highlighted transaction. | Paste Trans in the object menu.
Select multiple transactions. | Ctrl + left click.
Edit the transaction. | Double-click the transaction.

This table describes briefly how to edit transactions with the keyboard.

To Do This... | Press This Key...
Select multiple successive transactions | Shift + UP/Down Arrow
Move the highlight bar to the next transaction. | Down Arrow
Move the highlight bar to the previous transaction. | Up Arrow
Move the highlight bar to a different transaction. | Home, End, Up/Down Arrow
Insert a transaction above the highlighted transaction. | Insert
Delete the highlighted transactions. | Delete
Copy the highlighted transactions, saving them to the transaction "cut-and-paste" buffer. | CTRL+C
Paste the transactions currently in the buffer above the highlighted transaction. | CTRL+V
Cut the highlighted transactions, saving them to the transaction "cut-and-paste" buffer. | CTRL+X
Undo last operation. | CTRL + Z
Redo last operation. | CTRL + Y
Move single transaction up or down. | CTRL + Up/Down Arrow

To edit the fields within a transaction, double-click the transaction to expand it to an I/O Transaction dialog box as shown below.

The fields shown in the I/O Transaction dialog box are different for different types of I/O operations. To change information in a field, click on the arrow and select from the list that appears. Fields without an arrow require you to enter text. Click OK to accept the selections and return to the I/O object.

Clicking NOP saves the latest settings shown in the dialog box, and makes that transaction a "no operation" or a "no op." Its effect is the same as commenting out a line of code in a text-based computer program.

Input and output terminals are added automatically as needed. You can also use the Object menu to add or delete terminals.

Editing the Data Field

The data field requires you to enter text. The following figure shows an example of a READ Transaction and what you might enter in the data field.

This figure shows an example of a WRITE Transaction and what you might enter in the data field.

WRITE transactions allow you to specify an expression list (variables, constants and operators), but READ allows only a variable list. Typical entries for the data field are as follows.

Data Field Entry

Meaning

X

A

(READ) Read data into the variable X.

(WRITE) Write the value of the variable A.

X,Y

A,B

(READ) Read data into the variable X and then read data into the variable Y.

(WRITE) Write the value of the variable A and then write the value of the variable B.

null

A,A*1.1

(READ only) Read the specified value and throw it away. null is a special variable defined by VEE.

(WRITE only) Write the value of A and then write the value of A multiplied by 1.1.

"hello\n"

(WRITE) Write the Text literal hello followed by a newline character.

"FR ",Fr," MHZ"

(WRITE) Write a combination of Text literals and a numeric value. If the transaction is WRITE TEXT REAL and Fr has the Real value 1.234, then VEE writes FR 1.234 MHZ.

You may include the escape characters shown in table below in any field that accepts text input as a string delimited by double quotes.

note

READ transactions allow a null variable in the data field. Reading data into the null variable throws the data away. This is useful for removing unneeded data.

Escape Character | ASCII Code (decimal) | Meaning
\n | 10 | Newline
\t | 9 | Horizontal Tab
\v | 11 | Vertical Tab
\b | 8 | Backspace
\r | 13 | Carriage Return
\f | 12 | Form Feed
\" | 34 | Double Quote
' | 39 | Single Quote
\\ | 92 | Backslash
\ddd |  | The ASCII character corresponding to the three-digit octal value ddd.

See Also

Creating and Reading Transactions, Adding Terminals, Reading Transaction Data, Suggestions for Developing Transactions


Adding Terminals

To Add Terminals

VEE automatically adds input and output terminals as needed. To add one manually, click on "Add Terminal" in the object menu, or use the keyboard short cut CTRL+A.

WRITE transactions transfer data from VEE to the destination associated with the object and require a data input terminal. A WRITE transaction can also write data from a global or an expression such as "abs(globalA)"

READ transactions transfer data from the source associated with the object to VEE and require a data output terminal.

Variable names that appear on the terminal must match the variable names in the transaction specification, as shown below.

To edit a terminal variable name, do the following:

1 Double click the terminal to expand it into a Terminal Information dialog box.

2 Edit the Name field in the dialog box.

Variable names in VEE are not case-sensitive. Thus, s is the same as S and Signal is the same as signal.

See Also

Creating and Reading Transactions, Creating and Editing Transactions,Reading Transaction Data, Suggestions for Developing Transactions


Reading Transaction Data

To Read Transaction Data

To read data into a variable, VEE must know either the number of data elements to read or the specific terminating condition. READ transactions look for either a specified number of data elements or an end-of-file (EOF) indication. Specify this in the last field of the I/O Transaction dialog box.

Transactions that Read a Specified Number of Data Elements

The last field in the transaction dialog box has the default value SCALAR. This specifies that the READ transaction is to read only one element. To change this, click the SCALAR field and choose from a list of available choices.

The choices in the list indicate the number of dimensions for the READ transaction. For example, SCALAR indicates a dimension of 0, ARRAY 1D indicates a one-dimensional array, ARRAY 2D indicates a two-dimensional array, etc.

When you select a dimension, the transaction dialog box shows a fill-in field for each dimension specified. The figure below shows a transaction dialog box configured to read a three-dimensional array of binary integers into the variable named matrix. Each of the three fields after SIZE: contains the number of integers for the corresponding dimension. (In this case, each dimension has two elements.)

When more than one dimension is specified, the rightmost or "innermost" dimension is filled first. In this example, the elements are read in the following order:

   matrix[0,0,0] read first

   matrix[0,0,1]

   matrix[0,1,0]

   matrix[0,1,1]

   matrix[1,0,0]

   matrix[1,0,1]

   matrix[1,1,0]

   matrix[1,1,1] read last

When you click the OK button in the transaction dialog box, the resulting transaction appears with the ARRAY: keyword followed by the dimension sizes. For example:

   READ BINARY matrix INT32 ARRAY:2,2,2

If the transaction is configured to read a scalar value, the transaction appears as follows:

   READ BINARY x INT32

You can use variable names in the SIZE: fields to specify array dimensions programmatically. For example, the following transaction would read a three-dimensional matrix:

   READ BINARY matrix INT32 ARRAY:xsize,ysize,zsize

In this case, xsize, ysize, and zsize could be either the names of input terminals or the names of output terminals set by previous transactions in the same object.

Read-To-End Transactions

Certain VEE objects support READ transactions that read to the end-of-file (EOF). This makes it possible to read the contents of a file with a single transaction. Such transactions are called read-to-end transactions. The following VEE objects support read-to-end transactions:

  • From File

  • From String

  • To/From DDE

The following figure shows the transaction dialog box of a From File object, reading a three dimensional array of binary integers, but configured for read-to-end:

Read-to-end transactions are not supported for scalars. The transaction must be configured for at least a one-dimensional array to be configured as read-to-end. If a VEE object supports read-to-end, the SIZE: field appears as a button in the transaction dialog box. Clicking the SIZE: field enables read-to-end, and the field appears as TO END:.

If a one-dimensional array is read to the end, the number of elements in the array is unknown until EOF is found. The unknown size of the array is denoted by an asterisk (*) in the transaction.

When reading a multi-dimensional array is read to the end, the number of elements must be supplied for each dimension except the left-most or "outer" dimension. Above example shows that this dimension has an (*) in place of a size in the transaction. This dimension size is unknown until the read-to-end is transaction complete.

A three-dimensional array is nothing more than a number of two-dimensional arrays grouped together. A two-dimensional array has the dimensions of "rows" and "columns". Stacking two-dimensional arrays (like cards) adds the third dimension "depth".

In a read-to-end transaction of a three-dimensional array, the number of "rows" and "columns" is specified, but the "depth" is unknown until EOF is encountered. The same is true for all multi-dimensional read-to-end transactions. If the array has n dimensions, the size of n-1 of those dimensions must be specified. Only one (the left-most) dimension can be of unknown size.

In read-to-end transactions of dimensions greater than an ARRAY 1D, the number of total elements read has to be evenly divisible by the product of the known dimensions. For example, if the read-to-end example of a three-dimensional array is from a file with 16 total elements, the transaction will read four two-by-two arrays since the transaction specifies the number of "rows" and "columns" is equal to 2. Hence, the unknown dimension size, "depth", is 4 when the read is complete.

If the file actually contained 18 elements, one of the two-by-two arrays would be incomplete. It would contain only two elements. A read-to-end of this file would result in an error (and no data would be read) if you specified a size of 2 for the "row" and "column" dimensions. On the other hand, you could read this file if the number of "rows" is equal to 1 and the number of "columns" is equal to 3. A read-to-end of this file would then result in a "depth" of 6.

If you do not know the absolute number of data elements in a file, you can always use a read-to-end using ARRAY 1D.

note

The read-to-end transaction is useful with the Execute Program object for a program that is a shell command that will return an unknown number of elements.

See Also

Creating and Reading Transactions, Creating and Editing Transactions, Adding Terminals, Suggestions for Developing Transactions


Suggestions for Developing Transactions

Many times the best way to develop the transactions you need is by using trial and error. A large portion of the data handled by I/O transactions is text (as opposed to some type of binary data). Data written as TEXT is very useful for experimenting because it is human-readable. While using TEXT is not the most compact or fastest approach, you can use it to do just about anything.

You can use the To String object to accurately simulate the output behavior of other I/O objects writing text. The following program shows one way you might do this.

See Also

Creating and Reading Transactions, Creating and Editing Transactions, Editing Transactions, Reading Transaction Data


Choosing Correct Transactions

To Choose Correct Transactions

This section summarizes various I/O objects and the transactions they support. It also suggests a procedure for determining the correct object and transaction for a particular purpose. For details on transaction encodings and formats, refer to I/O Transaction Format.

Transaction-based objects available in VEE and the actions they support are summarized in the following tables .

Table 1:

Object | Description
To File From File | Writes data to a file. Reads data from a file.
To String From String | Writes text to a VEE container. Reads text from a VEE container.
To Printer | Writes text to the VEE text printer.
To StdOut To StdError From StdIn | Writes data to VEE standard output. Writes data to VEE standard error. Reads data from VEE standard input.
Direct I/O MultiInstrument Direct I/O Interface Operations | Communicates directly with GPIB, VXI, serial, or GPIO instruments. Communicates directly with multiple GPIB, VXI, serial, or GPIO instruments in the same object . Transmits low-level bus commands and data bytes on an GPIB or VXI interface.
To/From DDE | Dynamically exchanges data between programs running under Microsoft Windows.

Table2:

Action | Description
EXECUTE | Executes low-level commands to control the file, instrument, or interface associated with the transaction-based object. This action is used to adjust file pointers, clear buffers, close files and pipes and provide low-level control of hardware interfaces.
WAIT | Waits for a specified period of time before executing the next transaction. For Direct I/O to GPIB, message-based and I-SCPI-supported register-based VXI instruments, WAIT can also wait for a specific serial poll response.
READ | Reads data from the associated object.
WRITE | Writes data to the associated object.
SEND | Sends IEEE 488-defined bus messages (commands and data) to a GPIB interface.

Selecting Correct Objects and Transactions

1 Determine the source or destination of your I/O operation and the form in which data is to be transmitted.

2 Determine the type of object that supports the source or destination using above Table 1.

3 Determine the correct type of transaction using above Table 2.

4 To determine the remaining specifications for the transaction, such as encodings and formats, see WRITE Transactions, READ Transactions

Example: Selecting an Object and Transaction

For example, assume you need to read a file containing two columns of text data. Each row contains a time stamp and a real number separated by a white space. Each line ends with a newline character. A partial listing of the contents of the file is:

   14:18:00 1.001

   14:18:30 -2.002

14:19:00 1.0E-03 . . .

Based on the previous procedure for selecting objects and transactions, the steps to solve this problem are:

1 The source is a text file. The data consists of a time stamp in 24-hour hours-minutes-seconds notation and signed real numbers in scientific and decimal notation.

2 From Table 1, the object used to read a file is From File.

3 From Table 2, the type of transaction used to read data from a file is READ.

4 The required transactions are:

        READ TEXT x TIME

       READ TEXT y REAL

Using To String and From String

Use To String to create formatted Text by using transactions. The Text is written to a VEE container.

Use From String to read formatted Text from a VEE container.

If only one string is generated by all the transactions in a To String object, the output container is a Text scalar. If more than one string is generated by the transactions in a To String, the output is a one-dimensional array of Text.

WRITE transactions using EOL ON always terminate the current output string. This causes the next transaction to begin writing to the next array element in the output container.

WRITE transactions ending with EOL OFF will not terminate the output string, causing the characters output by the next WRITE transaction to append to the end of the current string. The last transaction in a To String always terminates the current string, regardless of that transaction's EOL setting.

For most situations, the proper type of transaction for use with To String is WRITE TEXT. For details about encodings other than TEXT, see WRITE Transactions, READ Transactions .

From String can read a Text scalar or an array depending on the configuration of the READ TEXT transaction. READ TEXT will either terminate a read upon encountering an EOL or will consume the EOL and continue with the read. This is dependent on the format. For details about formats, see WRITE Transactions, READ Transactions .

note

READ and WRITE Compatibility

In general, you must know how data was written to read it properly. This is particularly true when the data in question is in some type of binary format that cannot be examined directly to determine its format. You must read data in the same format it was written.


Using Transaction-Based Objects

To Use Transaction-Based Objects

This section gives guidelines for using transaction-based objects, including execution rules and Object configuration.

Execution Rules

Transaction I/O objects obey all general propagation rules for VEE programs. In addition, there are a few rules for the transactions themselves:

  1. Transactions execute beginning with the top-most transaction and proceed sequentially downward.

  2. Each transaction in the list executes completely before the next one begins. Transactions within a given object do not execute in an overlapped fashion. Similarly, only one transaction object has access to a particular source or destination at a time.

  3. Transaction-based I/O objects accessing the same source or destination may exist in separate threads or the same thread within the same program.

For file-related objects, there is only one read pointer and one write pointer per file. The same pointers are shared by all objects accessing a particular file.

Object Configuration

In the most general case, the result of any transaction is actually determined by two things:

  • The specifications in the transaction

  • The settings accessed via Properties in the object menu

In most cases you do not need to be concerned about the Properties settings as the default values are generally suitable.

Transaction-based I/O objects that write data (except Direct I/O) include an additional tab in the Properties dialog box that lets you edit the data format. The resulting dialog box allows you to view and edit various settings.

Note

Direct I/O objects include a Show Config feature in their object menu that allows you to view (but not edit) configuration settings. To edit the configuration of a Direct I/O object, you must use I/O [image] Instrument Manager.

Double clicking the title bar of a transaction I/O object yields a Properties Window as follows.

The Properties Window has a Data Format tab containing settings that affect the way certain data is written by WRITE transactions. The End Of Line (EOL) affects any WRITE in which EOL ON is set. The remaining Data Format fields affect only WRITE TEXT transactions.

The following sections explain the fields in the Data Format tab in detail.

End Of Line (EOL) Field

The End Of Line (EOL) field specifies the characters that are sent at the end of WRITE transactions that use EOL ON. The entry in this field must be zero or more characters surrounded by double quotes. "Double quote" means ASCII 34 decimal. VEE recognizes any ASCII characters within End Of Line (EOL) including the escape characters shown in Escape Characters Table.

Array Separator Field

The Array Separator field specifies the character string used to separate elements of an array written by WRITE TEXT transactions. The entry in this field must be surrounded by double quotes. "Double quote" means ASCII 34 decimal. VEE recognizes any ASCII character as an Array Separator as well as the escape characters shown in Escape Characters Table.

WRITE TEXT STR transactions in Direct I/O objects that write arrays are a special case. In this case, the value in the Array Separator field is ignored and the linefeed character (ASCII 10 decimal) is used to separate the elements of an array. This behavior is consistent with the needs of most instruments.

Multi-Field Format Field

The Multi-Field Format field specifies the formatting style for multi-field data types for WRITE TEXT transactions. The multi-field data types in VEE are Coord, Complex, PComplex and Spectrum. Other data types and other formats are unaffected by this setting.

Specifying a multi-field format of (...) Syntax surrounds each multi-field item with parentheses. Specifying Data Only omits the parentheses, but retains the separating comma. For example, the complex number 2+2j could be written as (2,2) using (...) Syntax or as 2,2 using Data Only syntax.

VEE allows arrays of multi-field data types. For example, you can create an array of Complex data. In such a case, if Multi-Field Format is set to (...) Syntax, the array will be written as:

   (1,1)array_sep(2,2)array_sep ...

where array_sep is the character specified in the Array Separator field.

Array Format Field

The Array Format field determines the manner in which multidimensional arrays are written. For example, mathematicians write a matrix like this:

   1 2 3

   4 5 6

   7 8 9

VEE writes the same matrix in one of two ways, depending on the setting of Array Format. In the two examples that follow, End Of Line (EOL) is set to "\n" (newline) and Array Separator is set to " " (space).

   1 2 3 Block Array Format

   4 5 6

   7 8 9

1 2 3 4 5 6 7 8 9 Linear Array Format

Either array format separates each element of the array with the Array Separator character. Block Array Format takes the additional step of separating each row in the array using the End Of Line (EOL) character.

In the more general case (arrays greater than two dimensions), Block Array Format outputs an End Of Line (EOL) character each time a subscript other than the right-most subscript changes.

For example, if you write the three-dimensional array A[x,y,z] using Block array format with this transaction:

WRITE TEXT A

an End Of Line (EOL) character will be output each time x or y changes value.

If the size of each dimension in A is two, the elements will be written in this order:

A[0,0,0] A[0,0,1]<EOL Character>

A[0,1,0] A[0,1,1]<EOL Character>

<EOL Character>

A[1,0,0] A[1,0,1]<EOL Character>

A[1,1,0] A[1,1,1]<EOL Character>

After A[0,1,1] is written, x and y change simultaneously and consequently two <EOL Character>s are written.


Communicating With Files

This section gives guidelines for communicating with files, including using file pointers and importing data.

Using File Pointers

VEE maintains one read pointer and one write pointer per file regardless of how many objects are accessing the file. A read pointer indicates the position of the next data item to be read. Similarly, a write pointer indicates the position where the next item should be written. The following table shows objects and source/destination files.

Source or Destination | Object
Data Files | To File, From File
Standard Input | From StdIn
Standard Output | To StdOut
Standard Error | To StdErr

The position of these pointers can be affected by:

• A READ, WRITE, or EXECUTE action

• The Clear File at PreRun & Open setting in the open view of To File

All objects accessing the same file share the same read and write pointers, even if the objects are in different threads or different contexts.

A file is opened for reading and writing when either of these conditions is met:

• The first object to access a particular file operates for the first time after PreRun. This is the most common case.

• New data arrives at the optional control input terminal that specifies the file name. This case occurs less frequently.

Read Pointers

At the time From File opens a file, the read pointer is at the beginning of the file. Subsequent READ transactions advance the file pointer as required to satisfy the READ. You can force the read pointer to the beginning of the file at any time using an EXECUTE REWIND transaction in a From File object. Data in the file is not affected by this action.

Write Pointers

The initial position of a write pointer depends on the Clear File at PreRun & Open setting in the open view of To File. If you enable Clear File at PreRun & Open, the file contents are erased and the write pointer is positioned at the beginning of the file when the file is opened. Otherwise, the write pointer is positioned at the end of the file and data is appended.

You can force the write pointer to the beginning of the file at any time using an EXECUTE REWIND or EXECUTE CLEAR transaction. REWIND preserves any data already in the file. However, new data will overwrite old data starting at the new position. CLEAR erases data already in the file.

note

The To DataSet and From DataSet objects also share one read and one write pointer per file with the To File and From File objects. However, mixing To DataSet and From DataSet operations with To File and From File operations on the same file is not recommended.

Closing Files

VEE guarantees that any data written by To File is written to the operating system when the last transaction completes execution and all output terminals have been activated.

VEE automatically closes all files at PostRun. PostRun occurs when all active threads finish executing.

Files may be closed programmatically by using the EXECUTE CLOSE transaction in both To File and From File. This provides a means to continually read or write a file that may have been created by another process.

Files may also be deleted programmatically by using the EXECUTE DELETE transaction. This is useful for deleting temporary files.

An example using EXECUTE CLOSE is shown below. This program is saved in the file manual48.vee in the examples directory.

Execute Program executes a shell command (date) that creates and writes the date and time to a file (\tmp\dateFile). Within the same thread, a From File reads the date from that file using a READ TEXT x STR transaction. The EXECUTE CLOSE transaction is necessary because the subthread is executed multiple times by For Count.

Succeeding executions of Execute Program will overwrite the file. However, since From File only opens the file once, upon the second execution of From File the read pointer will be stale. It will no longer point to the file because Execute Program has re-created the file. An error will occur.

From File must close the file after reading the data by using an EXECUTE CLOSE transaction. The EXECUTE CLOSE transaction forces From File to re-open the file on every execution.

In this example, the error can be shown by using an NOP to "comment out" the EXECUTE CLOSE transaction. The error will state End of file or no data found. Removing the NOP will allow the program to run normally.

EOF Data Output

From File supports a unique data output terminal named EOF (end-of-file). This terminal is activated whenever you attempt to read beyond the end of a file. The EOF terminal is useful when you want to read a file of unknown length.

The read-to-end feature also provides a means of reading a file of unknown length. However, the contents of the file will be in a single VEE container. If the file is to be read an element at a time, with each element residing in its own container, use the EOF terminal.

The next example illustrates a typical use of EOF. The file being read contains a list of X-Y data of unknown length. Typical contents of the file are:

   1.0

   5.5

   2.1

   8

   .

   .

.

Importing Data

Because VEE provides a convenient environment for analyzing and displaying data, you may want to import data into VEE from other programs. The general procedure to use for importing data from another software application is:

1 Save the data in a text file (ASCII file).

2 Examine the data file with a text editor to determine the format of the data.

3 Use a From File object with a READ TEXT transaction to read the data file.

Importing X-Y Values

One very common problem is reading a text file containing an unknown number of X and Y values and plotting them. The program below solves this problem.

The above program is saved in the file manual29.vee in the examples directory.

The READ TEXT REAL64 transaction easily handles all the different notations used for Y values, including signs, decimals and exponents. A portion of the data file is:

   .

   .

   .

   8 8.555555

   9 9e0

   10 1.05e+01

   11 +11.

   12 12.5

13 1.3E1

Importing Waveforms

Other software applications have many different conventions for saving waveforms as text files. In general, the file consists of a number of individual values that describe attributes of the waveform and a one-dimensional array of Y values. This section illustrates how to import waveforms saved using one of these conventions:

• Fixed-format file header. Waveform attributes are listed in fixed positions at the beginning of the file, followed by a one-dimensional array of Y data.

• Variable-format file header. A variable number of attributes are listed at the beginning of the file, followed by a one-dimensional array of Y data. Their positions are marked by special text tokens.

Fixed-Format Header

A portion of the data file with fixed_format is:

   NAME Noise1

   START_TIME 0.0

   STOP_TIME 1.0E-03

   SAMPLES 32

   DATA

                        .243545

                       .2345776

   .

   .

   .

Since this is a fixed-format header, labels such as NAME and SAMPLES are irrelevant. The waveform attributes always appear and are in the same position. The following example shows a program that reads the above waveform data file.

The program above is saved in the file manual30 .vee in your examples directory.

The transactions in From File do most of the work here. Here is how each transaction works:

1 The first transaction strips away the NAME label. This must be done before attempting to read the string that names the waveform, or NAME and Noise1 will be read together as a single string.

2 The second transaction reads the string name of the waveform.

3 The third through fifth transactions read the specified numeric quantity. VEE reads and ignores any preceding "extra" characters in the file not needed to build a number.

4 The sixth transaction reads the one-dimensional array of Y data using the ARRAY SIZE determined by the previous transaction. Samples must appear as an output terminal to be used in this transaction.

Variable-Format Header

Here is a portion of the data file with variable-format header:

   First Line Of File

   <MARKER1> 1 2 3

   <MARKER2> A B C

   <DATA>

   1 1.1

   2 2.2

   3 2.9

   .

   .

.

In this case, the exact contents and position of data in the file are not known. The only fact known about this file is that a list of XY values follows the special text marker <DATA>.

To simplify this example, this program finds only the data associated with <DATA>. In your own applications, you might need to search for several markers.

This program is saved in the file manual31.vee in your examples directory.

From File #1 reads tokens (words delimited by white space) one at a time, searching for <DATA>. Once <DATA> is found, From File reads XY pairs until the end of the file is reached.

See Also

L ab 5-3: Using the To/From File Objects


Communicating With Programs

This section gives guidelines to communicate with programs including:

• Using Execute Program

• Using Dynamic Data Exchange (DDE)

This table shows programs and related objects.

Program | Object(s)
MS-DOS command | Execute Program
Windows Application¨ | Execute Program To/From DDE
C program | Execute Program Import Library Call Function Formula

¨ VEE supports ActiveX automation, which lets you control other Windows applications. For information about using this feature, refer to Help [image] Content and Index [image] Tell me about [image] Active X.

Using Execute Program

You can use The Execute Program object to perform a task you would normally do from the Operating System command line. This is an example of the Execute Program object.

You can use Execute Program to run any executable file including:

• Compiled C programs

• Any MS-DOS program (*.EXE or *.COM files)

• .BAT files

• MS-DOS system commands, such as dir

Execute Program Fields

The following sections explain the fields visible in the open view of Execute Program.

Run Style

If the program you want to execute runs in a window, Run Style specifies the window style:

• Normal runs the program in a standard window.

• Minimized runs the program in a window minimized to an icon.

• Maximized runs the program in a window enlarged to its maximum size.

Wait for Prog Exit

Wait for prog exit determines when VEE completes operation of the Execute Program object and activates any data outputs. If Wait for prog exit is set to Yes, VEE will:

1 Execute the command specified in the Execute Program object.

2 Wait until the process terminates before activating any output pins of the Execute Program object.

If Wait for prog exit is set to No, VEE will:

1 Execute the command specified in the Execute Program object.

2 Activate any data output pins on the Execute Program object.

All other things being equal, Execute Program executes fastest when Wait for prog exit is set to No.

Prog With Params

Prog with params specifies either:

1 The name of an executable file and command line parameters.

2 A command that will be sent to MS-DOS for interpretation.

If you have included the appropriate path in the PATH variable in your AUTOEXEC.BAT file, you do not need to include the path in the Prog with params field. Examples of what you typically type into the Prog with params field are:

To execute a MS-DOS command:

COMMAND.COM /C DIR *.DAT

To run a compiled C program:

MyProg -optionA -optionB

To open a URL in a browser:

http://www.agilent.com/find/vee

To open a document:

D:\path\word.doc

Working Directory

Working directory points to a directory where the program you want to execute can find files it needs. For example, if you want to run the program make using the makefile in the directory c:\progs\cprog1:

1 In Prog with params:, enter nmake.

2 In Working directory:, enter c:\progs\cprog1.

Using Dynamic Data Exchange (DDE)

note

DDE is an obsolete (but still supported) feature. VEE for Windows supports ActiveX Automation, which lets you control other Windows applications. For information about using this feature, refer to Help [image] Content and Index [image] Tell me about [image] Active X. Agilent highly recommends using ActiveX Automation, instead of DDE.

Dynamic Data Exchange (DDE) defines a message-based protocol for communication between Windows applications. This communication takes place between a DDE client and a DDE server. The DDE client requests the conversation with the DDE server. The client then requests data and services from the server application. The server responds by sending data or executing procedures.

A Windows application that supports DDE may act as either a client, a server or both. VEE provides only client capabilities. It implements DDE capabilities with the To/From DDE object.

The To/From DDE object uses four types of transactions:

READ(REQUEST) | Reads Data from a DDE transfer.
WRITE(POKE) | Writes (pokes) Data to a DDE transfer.
EXECUTE | Sends a command to the DDE server that VEE is communicating with. The server then executes the command.
WAIT | Waits for the specified amount of time (in seconds).

The To/From DDE object initiates and terminates DDE operations as part of its function. You do not need to explicitly perform the initiate and terminate functions.

As shown below, the To/From DDE object has three main fields, Application, Topic, and Timeout.

In the Application field enter the DDE application name for the Windows application that you want to communicate with. Generally, this is the .EXE file name. See the manual for each specific application to determine its DDE application name.

The Topic field contains an application-specific identifier of the kind of data. For example, a word processor's topic would be the document name.

The Timeout field lets you specify the timeout period for VEE to wait if the application does not respond. The default value is five seconds.

The last field contains transactions to communicate with the other application. For READ(REQUEST) and WRITE(POKE) transactions, you must also fill in an Item name in the transaction. An Item name is an application-specific identifier for each piece of data. For example, a spreadsheet data item might be a cell location, or a word processor data item might be a bookmark name.

The To/From DDE object below, communicating with the MS Windows Program Manager, creates a program group, adds an item to the group, displays it for 5 seconds and then deletes the program group.

If the server DDE application is not currently running, VEE attempts to start that application. This will only be successful if the application's executable file name is the same as the name in the application field. The executable file's directory must also be defined in your PATH. VEE will try to start the application for the amount of time entered in the Timeout field.

If the executable file’s directory is not in your PATH, use an Execute Program object before the To/From DDE object to run the application program as follows.

The next example shows the use of input and output terminals with a To/From DDE object.

DDE Examples

Here are some examples of communication with various Windows software applications. Read the Note Pad in each example for important information regarding the example.

Lotus 123 DDE Example:

Excel DDE Example:

Reflections DDE Example:

Word for Windows DDE Example:

WordPerfect DDE Example:


Using Transactions in Direct I/O and Interface Operations

Three VEE objects allow you to communicate with instruments using I/O transactions:

• The Direct I/O object allows you to transmit data to and from instruments via the GPIB, VXI, serial, and GPIO interfaces and via a LAN connection.

• The MultiInstrument Direct I/O object allows you to perform direct I/O transactions to multiple instruments from a single object.

• The Interface Operations object allows you to send low-level GPIB or VXI messages, commands, and data.

For any of these objects, the messages are "constructed" and sent by means of I/O transactions.

note

Register-based VXI devices can be used as message-based only if supported by I-SCPI drivers.

You must properly configure VEE to communicate with instruments before you can use the Direct I/O, MultiInstrument Direct I/O, and Interface Operations objects. See Instrument Manager for details.


Using the Direct I/O Object

The Direct I/O object allows you control an instrument directly using the instrument's built-in commands. You do not need a VEE instrument driver (ID) or VXIplug&play driver to use Direct I/O to control an instrument.

Sending Commands

Use WRITE transactions to send commands to an instrument using Direct I/O. The most important WRITE transactions for sending commands to GPIB, message-based VXI, register-based VXI supported by I-SCPI, and serial instruments are:

WRITE TEXT

WRITE BINBLOCK

WRITE STATE

Direct I/O uses only WRITE BINARY and WRITE IOCONTROL transactions to send commands to GPIO instruments.

Direct I/O uses WRITE REGISTER and WRITE MEMORY transactions to send commands to register-based and some message-based VXI instruments. These transactions are the only method of communicating with register-based VXI instruments not supported by I-SCPI drivers.

WRITE TEXT Transactions

WRITE TEXT transactions are all you need to set up instruments for the majority of all situations where Direct I/O is required. Most GPIB, message-based VXI, and serial instruments use human-readable text strings for programming commands. Such commands are easily sent to instruments using WRITE TEXT transactions.

For example, all instruments conforming to IEEE 488.2 recognize *RST as a reset command. The transaction used to reset such an instrument is:

   WRITE TEXT "*RST" EOL

Instruments often define very precise "punctuation" in their syntax. They may demand that you send specific characters after each command or at the end of a group of commands. In addition, GPIB instruments vary in their use of the signal line End-Or-Identify (EOI).

If you suspect you are having problems in this area, examine the END(EOI)on EOL and EOL Sequence fields in the Direct I/O tab of the Advanced Instrument Properties dialog box. See Advanced Instrument Properties Dialog Box: Direct I/O Tab. See your instrument programming manual to determine the proper command syntax for your instrument.

  • Direct I/O allows you to use WRITE encodings other than TEXT when it is required by the instrument. The encodings other than TEXT that are most often useful are BINBLOCK and STATE.

WRITE BINBLOCK Transactions

BINBLOCK encoding writes data to instruments using IEEE-defined block formats. These block formats are typically used to transfer large amounts of related data, such as trace data from oscilloscopes and spectrum analyzers. Instruments usually require a significant number of commands before accepting BINBLOCK data. See your instrument's programming manual for details.

To use BINBLOCK transactions, you must properly configure the Conformance field (and possibly BINBLOCK) in the Direct I/O tab of the Advanced Instrument Properties dialog box. See Advanced Instrument Properties Dialog Box: Direct I/O Tab.

WRITE STATE Transactions

Some GPIB and message-based VXI instruments support a learn string capability, which allows you to upload all of the instrument settings. Later, you can recall the measurement state of the instrument by downloading the learn string using a WRITE STATE transaction. Learn strings are particularly useful when you wish to download measurement states but an instrument driver is unavailable.

note

WRITE STATE transactions are available for GPIB and message-based VXI instruments only.

A typical procedure for using learn strings is:

1 Configure the instrument to the desired measurement state. Typically, this is done using the instrument front panel.

2 Click Upload State in the object menu of a Direct I/O object configured for the instrument. The instrument state is now associated with this particular instance of the Direct I/O object.

3 Add a WRITE STATE transaction to the Direct I/O object.

  • When it is used, WRITE STATE is generally the first transaction in a Direct I/O object. WRITE STATE writes the Uploaded learn string to the instrument, setting all instrument functions simultaneously. Subsequent WRITE transactions can modify the instrument setup in an incremental fashion.

The behavior of Upload and WRITE STATE for GPIB and message-based VXI instruments is affected by the Direct I/O tab settings for Conformance and State (Learn String).

If Conformance is IEEE 488.2, VEE automatically handles learn strings using the IEEE 488.2 *LRN? definition. If Conformance is IEEE 488, Upload String specifies the command used to query the state, and the Download String specifies the command that precedes the string when it is downloaded.

Message-based VXI instruments and register-based VXI instruments supported by I-SCPI are IEEE 488.2 compliant.

Clicking Upload State in the Direct I/O object menu has these results:

The learn string is uploaded immediately.

The learn string remains with that particular Direct I/O object as long as it exists, until the next Upload. The learn string is saved with the program.

If you clone a Direct I/O object, its associated learn string is included in the clone.

Learn String Example

For example, suppose you want to program the HP 54100A digitizing oscilloscope using learn strings. Important facts for the oscilloscope are:

The oscilloscope conforms to IEEE 488. It does not conform to IEEE 488.2.

The command used to query the oscilloscope's learn string is SETUP?.

The SETUP command must precede a learn string that is downloaded to the instrument. A space is required between the P in SETUP and the first character in the downloaded learn string.

You must use the Instrument Manager to specify the proper direct I/O configuration for the oscilloscope. The settings for learn strings is shown as follows.

To upload a learn string from the oscilloscope, click Upload in the object menu of a Direct I/O object that controls the oscilloscope. To download the learn string, use this transaction:

   WRITE STATE

Reading Data

To read data from an instrument using Direct I/O, you can use READ transactions.

note

Instruments return data in a variety of formats. In general, you must know what kind of data and how much data you want VEE to read from an instrument. The kind of data determines the encoding and format you must specify in the transaction. The amount of data being read determines the configuration you must use for the SCALAR or ARRAY fields in the transaction dialog box.

The most important READ transactions for Direct I/O use with GPIB, message-based VXI, and serial instruments are:

READ TEXT

READ BINBLOCK

Direct I/O uses only READ BINARY and READ IOSTATUS transactions to read data from GPIO instruments.

Direct I/O uses READ REGISTER and READ MEMORY transactions to read data from register-based and some message-based VXI instruments. These transactions are the only method of communicating with register-based VXI instruments not supported by I-SCPI.

note

If you have difficulty reading data from instruments, try using the Agilent IO Monitor to examine the data format.

READ TEXT Transactions

Frequently, the data you read from an instrument as the result of a query is a single numeric value that is formatted as text. For example, a voltmeter returns each reading as a single number in exponential notation, such as -1.234E+00. The transaction to read a value from the voltmeter is:

   "READ TEXT a REAL"

Some instruments respond to a query with alphabetic information combined with the numeric measurement data. In general, this not a problem since READ TEXT REAL transactions discard preceding alphabetic characters and extract the numeric value.

note

When reading numeric data from an instrument, the data type of the instrument data is automatically converted, if necessary, according to the rules listed in Instrument I/O Data Type Conversions .


Using the MultiInstrument Direct I/O Object

The MultiInstrument Direct I/O object (I/O [image] Advanced I/O [image] MultiInstrument Direct I/O) lets you control several instruments from a single object using direct I/O transactions. The object is a standard transaction object and works with all interfaces that VEE supports.

It appears the same as the Direct I/O object, except each transaction in MultiInstrument Direct I/O can address a separate instrument. Since the MultiInstrument Direct I/O object does not necessarily control a particular instrument as the Direct I/O object does, the title does not list an instrument name, address, or live mode condition.

By using MultiInstrument Direct I/O, you can reduce the number of instrument-specific Direct I/O objects in your program, which optimizes icon-to-icon interpretation time. This performance increase is especially important for the VXI interface, which is faster than GPIB at instrument control.

Following figure is a MultiInstrument Direct I/O object and its I/O Transaction dialog box configured to communicate with four instruments.

Transaction Dialog Box

The I/O Transaction dialog box is similar to the one used by Direct I/O, except it contains two additional fields. The common fields work the same way. The following sections describe the two additional fields.

Instrument Field

The Instrument Field contains the name of any of the currently configured instruments. Clicking the down arrow presents a list of available configured instruments. You can select a different instrument for each transaction.

Address Field

The Address Field specifies the address of the device showing in the Instrument Field. The Address Field has two modes: Default Address and Address:.

Default Address sets VEE to use the address entered when the instrument was originally configured. Address: includes a text box that lets you enter a different address.

You can enter a specific numeric value, a variable name, or an expression. The entry must evaluate to a valid address. The value entered for Address: will change the device's address when the object executes, which is like the address control pin action. The following figure shows the I/O Transaction dialog box using Address:.

Editing Transactions

As you edit transactions using the I/O Transaction dialog box, only those transactions allowed by the type of instrument are accepted. For example, if the name showing in the Instrument Field is configured as a VXI device controlled via the VXI backplane, you can configure a REGISTER or MEMORY access transaction.

If the I/O Transaction dialog box is configured for a particular type of transaction and you change the Instrument Field name, the transaction must remain correct for the different instrument. If the transaction is incorrect, entries in the I/O Transaction dialog box will change to the last valid transaction for that instrument type. A REGISTER access transaction for a VXI device will be incorrect if you change the Instrument Field name to a non-VXI instrument.

Object Menu

The object menu for MultiInstrument Direct I/O is similar to that of the Direct I/O object. The MultiInstrument Direct I/O menu does not include the Show Config... or Upload State menu choices. These menu choices are for specific instrument configurations. Use the Direct I/O object to show an instrument's configuration or to upload a physical instrument's settings.

There is no live mode indicator for any of the possible devices in the transactions. To control live mode for an instrument, click I/O [image] Instrument Manager..., and then edit the selected instrument configuration.


Using the Interface Operations Object

The Interface Operations object (I/O [image] Advanced I/O [image] Interface Operations) allows you to control GPIB, VXI, and serial instruments using low-level commands. Interface Operations supports two types of transactions that provide this low-level control: EXECUTE and SEND.

The EXECUTE Transaction

EXECUTE transactions are of the form:

   EXECUTE Command

where Command is one of the bus commands summarized in Table Summary of EXECUTE Commands (Interface Operations). While the commands listed in this table have the same names as the EXECUTE commands in Direct I/O, there is an important difference.

• Direct I/O EXECUTE commands address an instrument to receive the command.

• Interface Operations EXECUTE commands may affect multiple instruments. For GPIB, these instruments must be addressed to listen.

Summary of EXECUTE Commands (Interface Operations):

Command | Description
ABORT | Clears the GPIB interface by asserting the IFC (Interface Clear) line. To clear and reset the VXI interface use CLEAR
CLEAR | Clears all GPIB devices by sending DCL (Device Clear). For VXI, resets the interface and runs the Resource Manager.
TRIGGER | For GPIB, triggers all devices addressed to listen by sending GET (Group Execute Trigger). For VXI, triggers TTL, ECL, or external triggers.
REMOTE | For GPIB, asserts the REN (Remote Enable) line. There is no counterpart for VXI.
LOCAL | For GPIB, releases the REN (Remote Enable) line. There is no counterpart for VXI.
LOCAL LOCKOUT | For GPIB, sends the LLO (Local Lockout) message. Any device in remote mode at the time LLO is sent will lock out front panel operation. There is no counterpart for VXI.
LOCK INTERFACE | In a multi-process system with shared resources, lets one process lock the resources for its own use during a critical section to prevent another process from trying to use them.
UNLOCK INTERFACE | In a multi-process system where a process has locked shared resources for its own use, unlocks the resources to allow other processes access to them.
PASS CONTROL | Passes control to a GPIB device at the specified address, provided the device is capable of becoming the active controller. There is no counterpart for VXI.

The SEND Transaction

SEND transactions are of this form:

SEND BusCmd

where BusCmd is one of the bus commands listed in Table SEND Bus Commands. These messages are defined in detail in IEEE 488.1. BusCmd is GPIB specific only. There are no counterparts for VXI.

SEND Bus Commands:

Command | Description
COMMAND | Sets ATN true and transmits the specified data bytes. ATN true indicates that the data represents a bus command.
DATA | Sets ATN false and transmits the specified data bytes. ATN false indicates that the data represents device dependent information.
TALK | Addresses a device at the specified primary bus address (0-30) to talk.
LISTEN | Addresses a device at the specified primary bus address (0-30) to listen.
SECONDARY | Specifies a secondary bus address following a TALK or LISTEN command. Secondary addresses are typically used by card cage instruments where the card cage is at a primary address and each plug-in module is at a secondary address.
UNLISTEN | Forces all devices to stop listening; sends UNL.
UNTALK | Forces all devices to stop talking; sends UNT.
MY LISTEN ADDR | Addresses the computer running VEE to listen; sends MLA.
MY TALK ADDR | Addresses the computer running VEE to talk; sends MTA.
MESSAGE | Sends a multi-line bus message. Consult IEEE 488.1 for details. The multi-line messages supported by VEE are: DCL Device Clear SDC Selected Device Clear GET Group Execute Trigger GTL Go To Local LLO Local Lockout SPE Serial Poll Enable SPD Serial Poll Disable TCT Take Control


I/O Configuration Techniques

This section provides information about instrument configuration with VEE..

The I/O Configuration File

The I/O configuration for each program can be embedded in the program file (recommended) or stored as a separate file. If it is stored as a separate file, it is the VEE.IO file. This file is stored in the following path:

%Appdata%\Agilent\ProductName\MajorVersionNumber + ".” + FirstDigitofProductMinorNumber

For example, the default location of VEE Pro 8.5 in Windows XP / 2K / Vista is %Appdata% \Agilent\VEE Pro\8.5.

When you configure instruments in a new program that does not contain an embedded configuration, the new settings are saved in memory for the remainder of your work session and in the VEE.IO or .vee.io file.

To keep the configuration, click the Save toolbar button. This saves the updated configuration with the program.

You cannot open any program containing an instrument control object unless your I/O configuration contains a device with a matching Name. In this discussion, Name means the entry in the Name field in the Instrument Properties dialog box, not the text in the object's title bar.

If the object is a Panel Driver or Component Driver, the ID Filename must also match your configuration. Settings other than Name and ID Filename do not affect your ability to open these programs, although other settings may affect how the programs run.

Changing the Configuration File

Generally, VEE takes care of the VEE.IO file. However, there are situations when you may want to erase, update, or copy this file outside the VEE environment.

If you want to run an instrument control program developed by someone else, but the I/O configuration is not embedded with the program, you need the I/O configuration that program uses. There are three ways to get it:

1 You can manually add all of the instruments to your configuration using the Instrument Manager and configuration dialog boxes.

2 You can copy the VEE.IO file for that program to your Agilent directory, using the path given at the beginning of this topic.

If you use the file copying method, save a copy of your original VEE.IO file to another name (such as VEEIO.OLD) in case you need it later.

3 You can save the program with the embedded configuration. Use the Save As option and be sure the "Save I/O configuration with program" option is checked.

note

Example programs were saved with embedded I/O configuration so the I/O configuration is self-contained. They do not depend on an external I/O configuration file.

Global I/O Configuration File

The default location of vee.io given at the beginning of this topic is a per-user and per-version directory, which means each user has one individual vee.io for every version of VEE that is used.

To use a global I/O configuration file for all users and all VEE products (Agilent VEE Pro, Agilent VEE Express, Agilent VEE Run, Agilent VEE Student), you need to define the global VEE Environment Variable. VEE saves and loads vee.io from the directory defined by the VEE Environment Variable if the VEE Environment Variable exists.

The VEE Environment Variable is named as

VEEHOME + ProductMajorNumber* + “.” + FirstDigitofProductMinorNumber*.

* ProductMajorNumber is the integer part of a product number. For example, for VEE 8.0, 8 is the product major number.

* FirstDigitofProductMinorNumber is the first digit of the product minor number. Product minor number is the fractional part of a product number. For example, for VEE8.51, 51 is the product minor number, its first digit is 5.

  • For VEE 8.5, the VEE Environment Variable is VEEHOME8.5.

  • For a patch release like VEE 8.51, the VEE Environment Variable would be the same as VEE8.5, which is VEEHOME8.5.

  • For VEE9.0, the VEE Environment Variable is VEEHOME9.0.

Refer to the help of Windows on how to define an Environment Variable.

NOte

So different VEE versions like VEE 8.0 and VEE 8.5 have different VEE Environment Variables. Do not set the VEE Environment Variables of different VEE versions to the same directory, for example, set VEEHOME8.5 and VEEHOME9.0 to the same directory. In this case, VEE 8.5 and VEE 9.0 share the same vee.io file, which may cause compatible issues between VEE 8.5 and VEE 9.0 if you add some items in vee.io file in VEE 9.0.

The global VEE Environment Variable is only used for vee.io file. There is no global configuration file for configurations other than I/O configuration.

See Also

Embedded I/O Configurations and Merging


I/O Control Techniques

This section describes some additional techniques for instrument I/O control.

Polling

VEE supports all serial poll operations defined by IEEE 488.1. All GPIB instruments and all VXI message-based instruments support serial poll operations. VXI message-based devices are, by definition, IEEE 488.2 compliant. VXI register-based devices are IEEE 488.2 compliant if an I-SCPI driver is available. VEE does not support parallel poll operations.

You can obtain an instrument's serial poll response in two ways:

Object | Serial Poll Behavior
Instrument Event | The Instrument Event object can poll the specified instrument once and output a scalar integer, which is the serial poll response using the NO WAIT option. The Instrument Event object can also wait for a specific bit pattern within the serial poll response byte by using a user supplied bit mask and the ALL CLEAR and ANY SET options.
Direct I/O | Direct I/O objects for GPIB instruments support a WAIT SPOLL transaction. This transaction repeatedly polls an instrument until the serial poll response byte matches a specific bit pattern, using a user-supplied bit mask and the ALL CLEAR or ANY SET options. See I/O Transactions for additional information about Direct I/O.

The Instrument Event object has special execution properties when configured for Spoll that are discussed in the next section, "Service Requests". This behavior allows other concurrent threads to continue execution while waiting for a specific bit pattern using the mask value and the ALL CLEAR or ANY SET options.

NO WAIT will execute immediately and return the status byte of the GPIB or message-based VXI instrument. Both objects have a Timeout control input available from their object menus (Add Terminal) so you can programmatically set a timeout period. Following figure shows an example.

Service Requests

To detect a service request (SRQ message) for a VXI instrument, use the Instrument Event object (I/O [image] Advanced I/O [image] Instrument Event). To detect a service request for a GPIB instrument or RS-232, use the Interface Event object (I/O [image] Advanced I/O [image] Interface Event).

The Instrument Event and Interface Event objects provide special behavior for interrupt-like execution. To view this behavior, you may wish to run your program with Debug [image] Show Execution Flow enabled.

For example, Interface Event behaves in a program as follows:

1 Before an Interface Event object (configured for GPIB and with the WAIT option specified) operates, execution proceeds normally with each thread sharing execution with equal priority.

2 When an Interface Event object operates, execution of the thread attached to the Interface Event data output pauses at the Interface Event object. Other threads not attached to Interface Event continue to execute.

3 When an SRQ is detected on the specified interface, the data output of Interface Event is activated. At this point, execution of all other threads is blocked until the thread attached to the data output of Interface Event completes execution.

Example: Service Request. The program that follows shows one way to handle service requests. In this example, it is possible that either dvm or scope is responsible for a service request. This program is saved in the file manual16.vee in the examples directory.

note

This program will run only if the specified instruments are connected, configured, and powered up. However, you can use this program as an example of programming techniques to use in your own programs or you can modify the program to communicate with your own instruments.

The program determines the originator of the service request by using Instrument Event to obtain the status byte of each instrument. Each status byte is tested using If/Then/Else and the bit(x,n) function to determine if bit 6 is true. If bit 6 is set, the corresponding instrument is responsible for the service request.

The Until Break object automatically re-enables the entire thread to handle any subsequent service requests. The Instrument Event object is configured for NO WAIT, meaning the status byte is returned without using the mask value. If a mask value of 64 is used and the Instrument Event object is configured for ANY SET, the If/Then/Else and bit(x,n) function need not be used.

Different instruments have different requirements for clearing and re-enabling service requests. In the above program dvm requires only a serial poll to clear and re-enable its SRQ capability. However, scope requires the additional step of clearing the originating event register.

The Instrument Event object can be used to detect a service request from a message-based VXI instrument. The instrument that writes a request true event (RT), which is evaluated as a request for service, into the VXI controller's signal register receives a Read STB word serial protocol command.

The message-based instrument sends its status byte back to the controller, and writes a request false event (RF) into the VXI controller's signal register. The status byte is used with the supplied mask value and the ANY SET or ALL CLEAR options to determine which bit (besides bit 6) is set. Thus one object, the Instrument Event, can be used to detect a service request from a message-based VXI device and determine why the request occurred.

Both objects have a Timeout control input available from their object menus (Add Terminal) so you can programmatically set a timeout period. For further information, see the Instrument Event and Interface Event.

Monitoring Bus Activity

You can use the Agilent IO Monitor (I/O [image] IO Monitor) to record all bus messages transmitted between VEE and any talkers and listeners. You can monitor any supported interface (GPIB, VXI, serial, or GPIO) using Agilent IO Monitor.

Agilent IO Monitor is a utility that traces the I/O calls of targeted library layers. For more information about using Agilent IO Monitor, open the Agilent IO Monitor (I/O [image] IO Monitor), then choose Help [image] Contents.

Low-Level Bus Control

You can send low-level bus messages in two ways as follows.

Object | Bus Message Capability
Interface Operations | This object allows you to send arbitrary bus messages to any GPIB device, or reset the VXI interface and fire various VXI backplane trigger lines.
Direct I/O | Direct I/O objects for GPIB, message-based VXI instruments, and I-SCPI supported register-based VXI instruments lets you send CLEAR, LOCAL, REMOTE, and TRIGGER commands using EXECUTE transactions.

For further information regarding Interface Operations and Direct I/O, see Using Transactions in Direct I/O and Interface Operations.

Instrument Downloading

Some instruments allow you to download macros, measurement routines, or complete measurement programs. For example, some HP instruments support HP Instrument BASIC in which you can write complete HP Instrument BASIC programs that execute inside the instrument. One approach for using VEE to download a measurement routine to an instrument is the following:

1 Create and maintain your measurement routine using a text editor, such as notepad. Save the measurement routine in an ordinary text file.

2 Use From File to read the file.

3 Use Direct I/O to write the contents of the file to the instrument.

This section presents a complete example of downloading using this approach. See Using the Direct I/O Object for further information regarding Direct I/O.

The following example program downloads a measurement subprogram to the HP 3852A. This example downloads subprogram BEEP2 that beeps twice and displays a message. This program is saved in the file manual17.vee in the examples directory.

note

This program will run only if the specified instruments are connected, configured and powered up. However, you can use this program as an example of programming techniques to use in your own programs or you can modify the program to communicate with your own instruments. This program, manual17.vee, has embedded configuration.

Below are the contents of the downloaded file manual17.dat. The manual17.dat file is provided in the examples directory.

   DISP MSG "LOADING BEEP2"

   WAIT 1

   SUB BEEP2

   DISP "BEEP2 CALLED"

   BEEP

   WAIT .5

   BEEP

   SUBEND

   DISP MSG "BEEP2 LOADED"


Logical Units and I/O Addressing

To access an I/O device, you will need to determine the correct address and enter it in the Address field in the Instrument Properties dialog box, using the Instrument Manager as described in Instrument Manager.

This section covers the VEE I/O addressing scheme, including interface logical units and instrument addresses, that supports Direct I/O, Panel Driver, and Component Driver I/O operations. This addressing scheme is not used for VXIplug&play I/O operations. See “Configuring for a VXIplug&play Driver” for information about VXIplug&play addressing in VEE.

note

VEE also supports direct VXI backplane access for embedded VXI controllers, for the E1383A and E1483A VXLink interfaces for PC.

The VEE addressing scheme uses logical units that you can set up using the I/O Config utility program as part of installing and configuring the I/O libraries included with VEE. See Installing the Agilent I/O Libraries for information about installing and configuring the Agilent I/O libraries, and setting up logical units using I/O Config. It is recommended that you set logical units for interfaces according to Table Recommended I/O Logical Units below.

Table Recommended I/O Logical Units.

Logical Unit | PC
1 | GPIB (82340 or 82341)
2 | GPIB (82340 or 82341)
3 | GPIB (82340 or 82341)
4 | GPIB (82340 or 82341)
5 | GPIB (82340 or 82341)
6 | GPIB (82340 or 82341)
7 | GPIB (82340 or 82341)
8 | GPIB (82340 or 82341)
9 | COM1 serial port
10 | COM2 serial port
11 | COM3 serial port
12 | COM4 serial port
13 | GPIO (HP E2075)
14 | GPIB0 (National GPIB card)
15 | GPIB1 (National GPIB card)
16 | VXI (Embedded, or PC using VXLink)
17 | GPIB2 (National GPIB card)
18 | GPIB3 (National GPIB card0

Recommended I/O Logical Units for VEE

The following interface logical units are recommended for use with VEE. See Installing the Agilent I/O Libraries for information about installing and configuring the I/O libraries and setting up logical units for interfaces using the I/O Config utility program.

note

Logical unit 7 is the recommended default for the first GPIB card. Each card must have a unique logical unit.

Only logical units 14, 15, 17, and 18 are supported for National GPIB cards on the PC.

I/O Addressing

Addressing schemes for various types of devices are described in the following sections.

To Address Serial Ports

Serial ports are supported by using the logical units that you assign to them using I/O Config. Normally, the COM1 serial port is assigned logical unit 9 . In this case, use 9 as the address of the device connected to COM1.

To Address GPIO Devices

GPIO devices are supported by using the logical unit that you assign to the GPIO interface using I/O Config. Normally, the logical unit 13 is used for GPIO. In this case, use 13 as the address for the GPIO device.

To Address GPIB Interfaces and Devices

GPIB devices are addressed using the following scheme:

SPA[SA]

Where:

S | is the logical unit of the GPIB interface.
PA | is the primary address of a GPIB device (the valid range is 00 through 30).
SA | is the optional secondary address (the valid range is 00 through 31).

Two examples are:

• For a GPIB device at logical unit 7, primary address 01, enter 701 in the Address field of the Instrument Properties dialog box.

• For a GPIB device at logical unit 14, primary address 09, secondary address 02, enter 140902 in the Address field of the Instrument Properties dialog box.

GPIB Logical Units GPIB interfaces are supported by using the logical units that you assign to them using I/O Config. The recommended logical units for GPIB interfaces are as listed in Table Recommended I/O Logical Units above. If the recommended logical units (1 through 8) are configured by the I/O libraries for GPIB interfaces, VEE can theoretically access up to eight GPIB cards, which can be a mix of the supported cards:

• For an 82340 or 82341, the logical unit is assigned by the software. The logical units are assigned in the order: 7, 8, 1, 2, 3, 4, 5, and 6. However, each card must be set to a unique base address. (See the owner's manual for information on setting the base address.)

The National Instruments GPIB driver configures up to four GPIB cards with the designations GPIB0, GPIB1, GPIB2, and GPIB3. To access these GPIB cards, you must assign the logical units 14, 15, 17, and 18 to the GPIB cards using I/O Config. VEE does not support any other logical units for GPIB cards. Otherwise, the addressing is the same as for any other GPIB card.

To Address VXI Devices on the GPIB

To access VXI devices through the GPIB with an HP-IB command module, you can use secondary addresses. If you are using an HP E1406 Command Module in a VXI card cage, the primary address is set by a switch on the command module (default = 09) and the secondary address is the individual VXI device's logical address divided by eight.

For example, suppose you have an HP E1406A Command Module (address = 09) in a C-Size Mainframe, with the HP E1406A connected to the GPIB interface at logical unit 7. For an HP E1326B Multimeter in a VXI slot with its logical address set to 24, the multimeter address is 70903.

Two instrument drivers are provided to help you find the correct addresses for VXI devices connected by means of a GPIB command module:

• Use the hpe140x.cid driver to locate VXI devices connected by means of an HP E1405 or HP E1406 GPIB Command Module in a C-size VXI mainframe.

• Use the hpe1300a.cid driver to locate VXI devices connected by means of an HP E1306 GPIB Command Module in a B-size VXI mainframe. (This driver also supports the HP E1300 and HP E1301 B-Size VXI Mainframes, which include built-in command modules.)

To use either of these drivers, add an instrument panel for the driver using the Instrument Manager as described in Online help: Help [image] Content and Index [image] Tell me about... Instrument Control Fundamentals.

note

Do not enter a sub address value for VXI devices, except for modules in a VXI switch box. See the next section for details.

To Set Address/Sub Address Values

Most GPIB and VXI instruments do not use sub addresses. Do not enter a sub address value unless you are accessing a VXI switch box or one of the mainframe instruments that use sub addresses, such as the HP 3235A Switch/Test Unit or the HP 3488A Switch/Control Unit.

note

Sub address values are used only if you are using an HP Instrument Driver for a device that supports sub addresses. Do not use sub address values if you are using Direct I/O.

Two examples follow:

• To access a module in an HP 3235A Switch/Test Unit, enter the GPIB address (for example, 701) of the HP 3235A itself in the Address field of the Instrument Properties dialog box, using the Instrument Manager as described in Instrument Manager.

Enter the sub address of the individual module in the Sub Address field of the Advanced Instrument Properties dialog box (on the Panel Driver tab). For information on entries in the Sub Address field, see online help for the HP 3235A instrument driver (Help [image] Instruments).

• To access a module in a VXI switch box, enter the GPIB address of the switch box (for example, 70902) in the Address field and the sub address of the individual module in the Sub Address field. For information on entries in the Sub Address field, see online help for the VXI switch box instrument driver.

To Address the VXI Backplane Directly

VEE can address the VXI backplane directly for the following systems:

• An HP 623x VXI Pentium Controller.

• An EPC-7 or EPC-8 VXI Controller, provided the EPConnect software is installed.

• A PC connected to a VXI card cage using an HP E1383A or HP E1483A VXLink (ISA-to-VXI) interface, provided the EPConnect software is installed.

• An HP V743 VXI Embedded Controller.

Assuming recommended logical units have been set using I/O Config, VEE accesses the VXI backplane via logical unit 16. The address for a VXI device is the logical unit (16) with the logical address of the VXI device appended.

For example, suppose an HP EPC-7 VXI Controller and an HP 1411B Digital Multimeter are installed in a VXI mainframe. If the logical address of the HP 1411B is set to 24, the VXI address is 16024. You do not divide the logical address by 8 as you would if you were accessing the VXI device via GPIB.


Instrument I/O Data Type Conversions

On instrument I/O transactions, VEE performs automatic data-type conversions according to the following rules. In VEE 6 Execution Mode, the new data types are used, and no conversion is done. However, in VEE 5 and prior modes, the following conversions are still performed just as the VEE 5.0 version did, for backwards compatibility. For example, READ BINARY Int16 will return an Int16 in VEE 6 mode, but an Int32 in VEE 5 and prior execution modes.

Note

These data-type conversions are completely automatic, so you won't normally need to be concerned with them. However, the following list shows what happens in VEE 5 and prior execution modes.

On a READ transaction, Int16 or Byte (UInt8) values from an instrument are converted to Int32 values, preserving the sign extension. Also, Real32 values from an instrument are converted to 64-bit Real numbers.

On a WRITE transaction, integer or real values are converted to the appropriate output format for the instrument

If an instrument supports the Real32 format, VEE converts 64-bit Real values to Real32 values, which are output to the instrument. If the Real64 value is outside of the range for Real32 values, an error will occur.

If an instrument supports the Int16 format, VEE truncates Int32 values to Int16 values, which are output to the instrument. Real values are first converted to Int32 values, which are then truncated and output. However, if a real value is outside the range for an Int32, an error will occur.

If an instrument supports the Byte format, VEE truncates Int32 values to Byte (UInt8) values, which are output to the instrument. Real values are first converted to Int32 values, which are then truncated and output. However, if a real value is outside the range for an Int32, an error will occur.

See Also

Converting Data Types with Objects and Functions


Understanding Propagation

Propagation is the general flow of execution through your VEE program. The propagation guidelines define the order in which VEE objects operate. In general, propagation is determined by data flow, that is the flow of data from object to object within a VEE program.

Propagation Summary

The following is a summary of the propagation rules that VEE follows when a program executes in VEE 4 or higher execution mode:

Data flows through objects from left-to-right -- sequence flows from top-to-bottom.

All data and XEQ input pins must be connected.

Objects with no data input pins or sequence input pin connections operate first.

All data input pins must be activated before an object operates (except for the JCT object).

If the sequence input pin is connected, it must be activated before an object can operate.

Objects operate only once unless connected to a repeat object (for example, For Count), or unless forced to operate by an XEQ pin.

Control pins execute immediately and do not cause the object to operate or propagate.

When an error is generated from an object with an Error pin, the Error pin propagates instead of the data output pins. However, the sequence output pin is activated. (If there is no Error pin, an error message is displayed.)

Parallel subthreads may operate in any order.

Multiple threads may operate in any order.

Basic Propagation Order

Based on the propagation rules, the objects in a VEE program executing in VEE 4 or higher mode operate in the following basic order when you press Run:

1. Objects that have no data input pins, and which have no sequence input pins connected, operate first.

2. Other objects operate in the order determined by data flow. In other words, objects with data input pins operate only when data is present on all data inputs, except as noted in How Objects Operate.

3. The order of propagation can be modified by connecting sequence pins, which are described in Pins and Propagation.


Pins and Propagation

This topic summarizes all of the types of pins, and their effect on propagation.

Data pins input or output a data container.

An object will not operate until all of its data input pins are activated. (Except the JCT object, which operates when any data input pin is activated.)

After an object operates, its data output pins propagate (if no error conditions have occurred).

Control pins (optional) are inputs that affect the state of the object but have no effect on propagation.

Common control pins include Clear, Reset, and Default Value. Control pins are connected with dashed lines to indicate that propagation is not affected.

Sequence pins are used only to specify the order of execution.

An object operates only after all data input pins and sequence input pins (if connected) are activated.

A sequence output pin propagates after all the data output pins have activated and data flow has propagated as far as possible.

It is best not to use sequence pins to obtain correct propagation -- let data flow determine the order of execution instead.

A sequence input pin is activated by the presence of a data container, but the data in the container is ignored. A sequence output pin propagates an empty (nil) container when it activates.

Error pin (optional). You can add an Error pin to trap an error condition the object generates. The Error pin propagates the appropriate error number if an error condition occurs.

If an error occurs, the Error pin propagates instead of any data output pins. Only the error pin and the sequence output pin (if connected) propagate.

XEQ pin is a pin that forces an object to operate immediately (even if a data input pin has not yet been activated). Only the Collector, and Sample & Hold objects use an XEQ pin to force the object to execute immediately, and propagate its data.

The XEQ pin is activated by the presence of a data container, but the data in the container is ignored.

Note

Do not leave any data input pins or the XEQ pin unconnected, or an error will occur when you run your program.

You may leave data output pins, control pins, and Error pins unconnected. Sequence pins, more often than not, should be left unconnected.


Understanding Sequence Pins

This topic summarizes the role of sequence pins in propagation, focusing on their recommended use.

Sequence Pins are the top and bottom pins on VEE objects. The top input pin, if connected, must be pinged before the object will execute. It may be convenient to think of this pin as a trigger or hold-off pin.

The bottom output pin will propagate after the object’s data (or Error) outputs propagate, and propagation has continued to downstream objects as far as it can.

Connecting these sequence pins is generally not needed in most programs, and some user programs greatly overuse sequence pins. Overusing sequence pins can confuse the compiler, and more importantly can confuse other programmers (or you a year from now!) trying to understand, modify, and maintain your program. However, there are a few cases where these connections are required.

Loops

The top sequence input of a Loop (For Count, For Range, etc) is often connected to ensure the loop doesn’t begin until after something else finishes. Similarly, the bottom sequence output of a Loop is often connected to objects in your program that should execute after the loop finishes. That general flow is easy to see in the following diagram:

To/From File or DataSet

If your VEE program writes to a file, and later reads from that file, you may need sequence pins to ensure the program doesn't read from the file until the program has finished writing to it. Here are two examples:

Setting and Getting Variables

You typically need the sequence input of a Get Variable (or a Formula that uses a variable) connected to ensure the Set happens before the Get. For example:

Control Input Pins that Carry Data

Unfortunately, many control input pins to VEE objects actually carry data. For example, the "FileName" input on a ToFile, or the "Formula" expression input on a Formula. In these cases, a sequence line is required to ensure the VEE object with the control input doesn't execute until the data coming in the control input has been received.

Using Confirm/OK Buttons on Popup Panels

Often Confirm buttons are used as "Ok" and "Cancel" buttons on popup panels to prevent execution of objects until the operator has completed data entry. The sequence ordering is sometimes confusing for new users, as the natural instinct is to place the Ok after the Knob (because the operator interacts in that order). Experience with VEE makes it easier to view the Ok button as a "hold-off," something that releases the data beneath it. The following example shows the normal configuration of VEE Confirm buttons.

Try this program with the Ok connected after the Knob (with Show Data Flow and Show Execution Flow on) to understand why the Ok must execute first. Connect a display to the output of the UserObject to see whether the new or old value is propagated in each configuration.

Multiple Data Output Lines Mixed with Control Flow

There are a few cases when programs use multiple lines out the same pin, mixing data flow with control flow. This can cause programming errors that are difficult to detect. In the following example, assume the operator chose a value on the Knob and pressed Ok.

Will the Formula and propagation of the UserObject happen first, or will the Exit UserObject happen before the Formula? Will the UserObject output pin get a value before the Exit UserObject executes? This is not deterministic; it’s random. Here you need sequence pins.

See the previous example for a better way to connect the Exit UserObject sequence pin.

Common Cases of Over-Using Sequence Pins

Programmers with a background in procedural languages sometimes want to connect sequence pins when they are not needed. Here are some common examples where beginning VEE programmers connect sequence pins, but data flow has already determined program flow.

The unnecessary sequence connection may be easy to see in these simplified diagrams. But some programmers are tempted to add sequence connections in larger programs, even though the flow patterns are essentially the same as these.

A previous control-pin example can be confusing to some. There is no need for sequence lines when acceptable program flow is dictated by data pins. However, control pins do not dictate program flow like data pins do. The following two diagrams are similar, but not equal.

The control-flow model (dashed blue line) needs the help of sequence pins, the data-flow model (solid blue line) does not.


Propagation of Threads and Subthreads

A very simple VEE program usually contains only one thread. Programs that are more complicated contain additional threads and subthreads which affect the program’s propagation.

Threads – Objects connected through data and sequence lines, which are solid, form a thread. Objects connected only through control lines, which are dashed, are not considered to be in a thread. A program can contain several threads. For example, the following program contains two parallel threads. The threads are independent because they are not connected by data or sequence lines.

Subthreads -- A branch of a thread is called a subthread. When two subthreads begin at the same data output pin of the same object, and there are no sequence or data lines between them, they are parallel subthreads. The following program shows two parallel subthreads branching from the data output pin of the Real64 constant object:

Parallel threads and subthreads operate in random order with relation to each other. One or more objects (or all objects) in a thread will operate, then one or more in another thread operate. However, there are two exceptions to this:

If a thread contains an Interface Event or Device Event object, it takes over execution when an event is trapped. For example, if Interface Event detects an GPIB SRQ message, the thread will continue to completion before any other thread can continue. Other threads are held off to allow the event to be serviced. For further information, refer to Interface Event and Device Event.

If a thread has a Start object, and if you start the thread by pressing the Start button, that thread will run to completion before you can start any other threads.


How Objects Operate

A VEE object operates by accepting the data on its input pins, processing that data, and then returning the resulting data on its output pins. A VEE object will not operate until all of its data input pins are activated with data on them. (There is one exception: The JCT object will operate when one of its data input pins is activated with data.)

Let's look at a simple example. In the program below, the a+b object will not operate until there is data on both of its data input pins. Thus, both of the Real64 constant objects must operate first (in no particular order).

When the a+b object operates, it adds the data and activates its output pin with the resulting data. The AlphaNumeric object does not operate until its data input pin has data, so it operates last, displaying the result.

As you can see, data flow has determined the order of operation of the objects in the above program. That is, data flow determines the propagation order.

In addition to the data pins, the sequence pins can be used as a hold-off to control when an object operates. This is useful when you want to prevent data input pins from accepting any data until valid data is available. In the following program, a Confirm OK object has been added to the previous example:

The sequence output pin of the Confirm OK object is connected to the sequence input pin of the a+b object. Sequence input pins need not be connected. That is, if a sequence input pin is not connected, it is ignored by the object. However, if a sequence input pin is connected, the object will not operate until it has been activated. So, in the above example the a+b object won't operate until you press (click on) the OK button. Then the data input pins accept the data.

The XEQ pin has the opposite effect on object operation. An object propagates immediately when the XEQ pin is activated using any data present on its data input pins. This is important to consider when using both the XEQ pin and sequence input pin on an object. The XEQ pin must be connected, and the object will not propagate until the XEQ pin is activated. Here is an example:

The For Count object repeats five times, outputting data to the Data input terminal on the Collector. The Collector collects the five values into an array, which it propagates when the XEQ terminal is activated by the sequence output pin of the For Count object.

Note

Remember that you can use Properties from the object menu to turn on Show Terminals. With Show Terminals turned on, the data input and output pins become "terminals", showing their names.


Some UserObject Concepts

A UserObject provides the means for you to encapsulate a group of objects that perform a particular task into a single, custom object. This encapsulation allows you to:

Use modular design techniques in building your VEE program. This allows you to solve a complex problem through an organized approach. UserObjects allow you to use top-down design techniques to create a more flexible and maintainable program.

Build user-defined objects that you can save in a library for later re-use.

Once a UserObject is created and saved, you can Merge it in other programs.

UserObject Features

When you add a UserObject to the Main Window, it appears in an icon view, and remains that way in your program. When you double-click the icon, the UserObject’s edit window pops up presenting the work area where you can build a specific program segment by adding objects and connecting them. The terminal areas accommodate data and control terminals so the UserObject can communicate with the rest of your program. The following figure shows the UserObject named UserObject1 in its icon view and edit window.

Contexts and UserObjects

The Main Window and UserObjects represent separate contexts within a VEE program, just as subprograms represent separate contexts within a C or BASIC program. As shown in the previous figure, you can nest UserObjects in a VEE program, which results in additional contexts. In the previous figure, there are three contexts. More objects can be added to each context.

1. The Main Window is one context which contains UserObject1.

2. UserObject1 is a context and contains UserObject2.

3. UserObject2 is a context which can contain other objects.

Propagation and UserObjects

Propagation in a program containing UserObjects is affected by the fact that a UserObject is a separate context. The UserObject propagation rules are as follows:

All data input terminals (and the sequence input terminal if connected) of the UserObject must be activated before any objects within the UserObject operate.

Once the data input terminals (and the sequence input terminal if connected) of the UserObject have been activated, the UserObject operates. The objects within the UserObject operate following the rules of propagation.

Programs written before VEE version 4.0 may contain an optional XEQ terminal. If it is activated, the UserObject immediately begins operation of the objects within its work area, using whatever "old" data may be on the inactivated input terminals of the UserObject. In most cases, you need not use the XEQ terminal for a UserObject. It is not available in VEE 4.0 and later versions, and existing programs with XEQ pins on UserObjects will not compile if run in the VEE 4 or higher execution mode.

The UserObject data output terminals do not propagate until all objects within the UserObject finish operating (unless the UserObject is exited prematurely by an error or an Exit UserObject). Only those output terminals activated from inside the UserObject pass data to objects outside the UserObject. When activated, each data output terminal propagates only one data container.

In programs written before VEE version 4.0 (running in the VEE 3 execution mode), the objects within the UserObject time-share in operation with external objects on different subthreads. This is time-slicing. The UserObject does not block the operation of objects outside the UserObject. In programs running in the VEE 4 or higher execution mode, the UserObject will time-slice only when invoked from separate threads.

For more information about the propagation rules, refer to Understanding Propagation.

Note

If there is a Start object in a UserObject, pressing Start runs only the objects connected to the same thread as the Start object. No data will be read from the input terminals of the UserObject, nor will its output terminals propagate. Therefore, no propagation outside the UserObject takes place.

Data Output from a UserObject

As stated in the propagation rules, each data output terminal of a UserObject propagates only one data container (the last received by the terminal) to the context outside the UserObject when the objects within the UserObject finish propagating. This can lead to unexpected results in your program if you neglect to account for it. The following example illustrates this situation:

Although the For Count object sends 10 data containers (the numbers 0 through 9) to the Count output terminal, only one data container (the last number) propagates from the UserObject. However, you can use a Collector object to collect the data from the For Count object into an array. The Array output terminal also propagates only one data container, but that container is a one-dimensional array of 10 values (0 through 9).


Controlling Program Flow

Though propagation rules in VEE are logical, it is not always obvious how a program will propagate. Here are some rules of VEE programming style:

• Build a program using program flow that is clear and propagates in a hierarchical fashion. If you can visualize the flow easily, you normally will not have problems.

• If the execution order between objects is important but ambiguous, connect sequence input and sequence output pins. Though you should not need to use them often, there are cases when they are necessary to ensure the execution order required for your program.

• Avoid using feedback loops for iterations. Such constructs cause unpredictable results. Loops are intended for passing back containers with data to the start of a thread. If you must use feedback, JCT (Junction) objects are required in feedback loops.

• Avoid parallel threads fed by a looping object. It is difficult to tell which thread will be executed.

• Avoid using Gate and Sample & Hold objects. These objects are mainly used as patches for poor knowledge of propagation rules. Good programming style helps avoid the need for these objects.

See Also

Basic Program Control Advanced Program Control


Basic Program Control

It is important to understand how basic combinations of objects work together to control program flow. The following program shows how to generate a simple count useful for a loop, a common program control. The For Count object counts from 0 through 9 when the program runs.

You can nest For Count objects to create nested loops. In the next program, the inner loop’s For Count counts from 0 through 9 for each count sent to its sequence input pin by the outer loop’s For Count. The outer For Count does not send its next output count until the inner For Count finishes its entire loop.

When the outer For Count sends its last count, it outputs a pulse from its sequence output pin, activating the Beep object. This is an important feature of such looping objects. They do not generate a sequence-out pulse until after the threads they are driving have executed.

Continuous Loops

To generate a continuous loop, you can use an Until Break object as shown in the next example. The Delay object controls the program to update once per second. A better approach is to replace the Until Break with an On Cycle, which can generate a container with any delay setting to drive the now() object. You can set the AlphaNumeric display format in its Properties dialog box on the Number tab.

A continuous loop is useful to repeat a program’s action until a certain condition is met. To end this loop at any time, add the OK, Break and Next objects as shown in the program below.

This example illustrates another feature of control constructs in two parallel threads. The program is intended to update the time continuously, until you press the OK to force the Break. Without the Next object, Until Break would generate a container, then wait until everything downstream from it executes. The time would update and the program would wait until OK is pressed. The Next object forces Until Break to output containers continuously until OK is pressed.

In this case, a Stop object could be used in the place of the Break object without making any difference.

To provide more direct control over the continuous loop, you can use a Toggle object. The following program shows how to use a Toggle (in its Button format) to break a loop.

The Toggle output is connected to its Reset control input. The default initial value is 0, which is output to the If/Then/Else during each loop. While the Toggle value remains 0, program flow continues to the Now object. Clicking the Toggle’s Button toggles the value to 1, which satisfies the expression’s condition in the If/Then/Else and activates the Break object.

Making Programs Interactive

Given the previous techniques for loops, the following program shows how to create a general architecture for interactive programs. Consider a simple program where the user can select one of two actions or exit the program by clicking the appropriate Toggle buttons:

The concept is that each separate action has its own parallel thread. The loop continuously checks each Toggle object’s output (initial value is 0) in each If/Then/Else expression. When a button is pressed, the Toggle’s output changes to 1, which sends the corresponding Text output to the AlphaNumeric display or ends the program. You can add as many parallel threads as you like to perform I/O and computation as needed.

The implication of this architecture is that the executing thread must finish before another thread can execute. If the executing thread takes a long time to finish, you will have to wait until this thread is finished before another thread can execute.

Note

Using above Toggle control techniques to control continuous loop will have impact on system performance because the Toggle buttons will run all the time and use up about 50% of CPU time. To avoid this, use OK and Next objects to replace the Toggle buttons. The program below shows how to use OK and Next objects to implement the above program. In this program, the OK buttons will use 0% of CPU time after the Until Break object until an OK button is pressed.

See Also

Controlling Program Flow, Advanced Program Control


Advanced Program Control

Your programs can perform more complicated control tasks if you expand the basic techniques.

Example: Initiating Program Tasks

As an example, the following program lets the user select one of several tasks or lets a service request (SRQ) from an instrument initiate a task.

When the program runs, you click the Task 1 or Task 2 buttons to get the appropriate display output. If you press the Clear Status on the Panel Driver’s Status Panel, you get the SRQ! message output, then return to perform another task. The program stops when you click the Quit button.

The Until Break object drives the four parallel threads within the program that are controlled by three Toggle buttons (Task 1, Task 2, Quit) and the Interface Event object (SRQ:GPIB7).

The two threads defined by the Task 1 and Task 2 buttons display the text Doing Task 1 and Doing Task 2 in the Message dialog box. The thread defined by the Quit button stops the program and clears the display.

The interesting thread involves the SRQ. The HP 54501A Panel Driver, connected to the Until Break object, is set with its SPoll Enable (on the Status Panel) set to request service. A service request is sent when the Clear Status button is pressed on the Status Panel. With the mask set, the thread that handles the SRQ uses the Interface Event object to wait for the SRQ by using the settings as follows.

When an SRQ occurs, the Interface Event object pings the Instrument Event object to do a serial poll, which clears the SRQ on the scope.

Since NO WAIT is set, this object does the serial poll and then pings the Text object. The SRQ! message is sent to the Message dialog box announcing that an SRQ has occurred. The Message dialog is configured to wait for the operator to respond. The mask value is irrelevant.

Calling Functions

The following program is similar. You can call one of three user-defined functions – A, B, or C – to initiate an action, then have the program continue to execute the selected function.

The Radio Buttons object lists the available functions. The Toggle buttons let you execute the selected function or quit the program. If you choose to execute a function, the function name is output to the as Text Formula object. AsText is a built-in function that converts inputs to the Text data type.

The text function name is output to the Call Function object’s control input, Function Name, so the selected function is called. When the program runs, the operator chooses a function name in the Radio Buttons object and presses the Execute Function button.

note

Control inputs have no effect on objects’ propagation. The asText sequence output is connected to the Call Function sequence input to hold off the Call Function propagation until after receiving the Function Name.

Clearing Strip Charts

In a related program flow problem, the following program generates a strip chart that is cleared after counting a certain number of points or whenever the user clicks a button:

The Until Break object drives the program. It controls the Quit Toggle, the Random Number, Clear Chart Toggle, and Counter objects through the sequence input and output pins. Random Number (the random(high, low) built-in function) object feeds values to the Strip Chart display. The Counter counts each loop iteration and outputs the count to the If/Then/Else. The If/Then/Else clears the Strip Chart and the Counter when a user presses the Clear Chart button or Count equals 100.

The Toggle Control object is driven continuously by Until Break, generating a 0 most of the time. Clicking Toggle Control toggles it to 1 and it is then reset by the feedback connection. The 1 is an input to the If/Then/Else. You can change the default appearance of the Toggle Control object by using Properties (object menu) to hide the Title Bar and then adding the Reset terminal.

NOte

Using above Toggle control techniques to control continuous loop will have impact on system performance because the Toggle buttons will run all the time and use up about 50% of CPU time. To avoid this, use OK and Next objects to replace the Toggle buttons. See Basic Program Control for an example.

See Also

Controlling Program Flow, Basic Program Control


Error Handling

Error handling is an important concept in VEE. It lets you perform an action then either repeat the action or continue after an error occurs. The following program demonstrates this with a dialog box to represent an action that can have different outcomes.

This program pops up the Exclamation Message Box asking if you want to Stop, Retry, or Ignore.

• Stop pings the Stop object to stop the program.

• Retry pings Next to reiterate the loop and redisplay the same Message Box.

• Ignore pings the Break object to stop the Until Break loop.

When Until Break stops, it pings the Question Message Box to offer more program-control options.

Notice that the element(s) to be executed sequentially after the “I/O” loop are connected to the sequence-out pin of the Until Break; they are not connected to any of the loop elements.

Avoid using error-handling as a standard practice, particularly with a Transaction object whose transactions contain complicated math formulas. VEE allocates memory to execute these formulas, and if an error occurs during execution that memory is not released, causing an incremental memory leak.

See Also

Capturing Control Pin Errors, Data Propagation on Control Pins, Building a Record, Multiple Inputs to a Formula, Timing Events


Capturing Control Pin Errors

Since control pins execute immediately and do not cause an object to propagate, certain conditions may cause your program to work incorrectly. If a control pin causes an error, you must use special programming techniques to capture the error programmatically.

In situations where a control pin causes an object to error, the program stops and VEE displays an error dialog. To capture and resolve the error programmatically, the typical solution is to add an Error output to the object. This solution works in most cases except when a control pin causes the error. Since control pins do not affect an object’s propagation, the object does not propagate the error information. That is, because the control pin does not cause the object to execute, the object cannot propagate. It is not allowed to propagate any output pins, including the Error pin, until it has executed. To capture an error caused by a control pin you must add an Error output to the context that contains the object.

The following program shows the wrong way to capture an error caused by a control pin. The program displays a waveform in the XY Trace display. The XY Trace has a Scales control input that requires a Record data type to change a scale on the display. Text and Integer provide values to the Build Record for the Scales control input. An Error output on the XY Trace is intended to capture any error condition, sending it to the errorInfo() function.

This program handles the error by displaying the error number and message. The program will capture any error generated in the XY Trace except when the Scales control input causes an error.

Running the program reveals the problem of trying to programmatically capture an error caused by a control pin. The Scales control pin expects a Record containing, at a minimum, the value identifying the scale being changed. Allowed values are X, Y, Y1, Y2 and Y3.

The control pin generates an error because it receives the incorrect value T from Text. Since it is a control pin error, there is no further propagation in XY Trace and the Error output does not receive the error information. The program stops abruptly and VEE displays the error dialog as follows.

As explained previously, the correct way to capture a control pin error is to add an Error output to the context containing the object. The next program shows a solution where the Build Record and XY Trace are put into a UserObject. Notice that the XY Trace display’s Error output has been deleted and an Error output is added to the UserObject. Also, the UserObject’s Error output has been connected to the errorInfo().

See Also

Error Handling, Data Propagation on Control Pins, Building a Record, Multiple Inputs to a Formula, Timing Events


Data Propagation on Control Pins

When an object’s control pin receives data, such as a file name or default value, you should connect the object’s sequence input pin or the program might fail. Since a control pin does not affect an object’s propagation, the object will propagate when the data inputs receive data even if the control pin’s value is not set.

The following program shows this sequencing problem. Alloc Array sends data to To File before the dataFile2 file name is sent to the File Name control pin. When To File receives the data, it immediately changes the contents in dataFile1 instead of the intended dataFile2. To File does receive the new file name on its control pin but it is too late.

To fix this problem, use To File’s sequence input to hold off the object’s operation until after the control pin receives its data. The following program shows that connecting File Name’s sequence output to To File’s sequence input ensures data is written to the correct file.

See Also

Error Handling, Capturing Control Pin Errors, Building a Record, Multiple Inputs to a Formula, Timing Events


Building a Record

When trying to build a record of three waveforms as follows, the Build Record object will never propagate. After the Function Generator sends its output to the DeMultiplexer, the For Range object starts its loop counting from 0 through 2. Each count sends the corresponding Addr out from the DeMultiplexer to the respective Build Record input.

note

Within a loop, when an object with multiple outputs, such as the DeMultiplexer, sends data from one output on each loop iteration the other output values are invalidated at the beginning of each loop. This prevents propagating possibly old, incorrect data to the next object. This is also true for an object with multiple inputs, such as the Build Record.

When one input receives data on each loop iteration, values on all of its other inputs are invalidated at the beginning of each loop. VEE works this way to prevent a program from working with previous rather than current values, which can cause incorrect results.

The Build Record object never propagates its Record output due to the way VEE loops work. In this program, each For Range iteration invalidates the data put on the Build Record’s inputs from the previous iteration. Since the Build Record object receives only one input on each loop iteration, only one input is valid at a time so there is no Record output.

Build this program yourself and turn on Show Data Flow to see how the DeMultiplexer only propagates one data output each time through the loop.

The next program makes this solution work as expected by using a UserObject. This solution works because a UserObject’s output terminals hold the data until the iterations are done. The data are valid on the Build Record inputs since the UserObject sends the three outputs at the same time. When all three inputs contain valid data, the Build Record object outputs the expected results.

The following program solves the problem by replacing the DeMultiplexer with a Shift Register. Unlike the DeMultiplexer that has only one valid output at a time, the Shift Register’s three outputs are valid simultaneously since they are all sent at the same time to the Build Record’s three inputs. Shift Register outputs that contain no data propagate a nil.

This particular program clocks three waveforms into the Shift Register and then pings the Build Record to generate a record of them. If you prefer an array instead of a record output, you can use a Collector.

See Also

Capturing Control Pin Errors, Data Propagation on Control Pins, Error Handling, Multiple Inputs to a Formula, Timing Events


Multiple Inputs to a Formula

Sending values to multiple inputs on a Formula object inside a loop can cause propagation problems if the values are sent during separate loop cycles. As shown previously with the Build Record object, the Formula will not operate if any input terminals contain invalid data. Using a DeMultiplexer object inside the loop adds to the confusion. Here is the program showing the problem.

The DeMultiplexer is driven by the For Count object to output a single value (0 through 3) for each cycle of the count. Only one value is output per cycle so the inputs to the Formula object are made invalid after each cycle. Since the two Formula inputs A and B are never valid at the same time, the Formula never executes and there is no Formula output.

You may have decided that the value of 2 on pin A is still useful during the next loop iteration, but VEE does not have that insight. The loop might be calculating several coefficients for the same formula. There is no logical reason to solve a formula with half old coefficients and half new coefficients. As a general rule, it is safest for a programming language to assume that data from a previous iteration is “stale.” That is why VEE invalidates an object’s inputs at the start of each loop iteration.

Working with Loops

There are ways to work with a situation where unchanged input values are invalidated after a loop iteration. An example in the previous section showed how a Shift Register delivers multiple valid outputs simultaneously. A direct way to accomplish most tasks involves using variables. The following program shows how to use variables to supply valid values to a Formula object.

There are two important points about the way the global variable Nval is used in this program. First, Nval is initialized when the program starts running. It is not necessary to do so in this particular program, since VEE initializes it before it is used, but it's a good programming practice. Second, Nval is always set with a new value before the Formula uses it.

You must be sure always to set a variable before an object must use it, or your program will have a problem similar to those with invalid data. If the variable is initialized, its value might be incorrect. If the variable is not initialized, your program will cause an error, such as Variable was not found.

See Also

Error Handling, Capturing Control Pin Errors, Data Propagation on Control Pins, Building a Record, Timing Events


Timing Events

The Timer object can display odd (possibly bad) results depending on how it is connected in a program. This program here demonstrates how VEE propagation issues should influence the way you connect objects in a program.

The “Blocks” in this program are arbitrary threads containing some combination of VEE objects. The Timer has been added to time how long Block 2 takes to execute. This program may run or cause an error. If it runs, the Timer may produce an erroneous result. There are two problems that affect when the Timer starts timing and when it ends.

First, the Block 1 sequence output “pings” both Block 2 and the Timer’s Time1 input. The program does not specify which to ping first so it can choose either. If it chooses Block 2 first, it will not ping Time1 until Block 2 is done. This condition can cause a bad timing result or an error if Block 2’s output pings Time2 before Time1 is pinged.

Even if you turn on the Show Data Flow debugging feature to help identify the problem, the data flow indicators may not fully indicate the actual propagation. In this situation, propagation depends on the order in which you connected the lines from Block 1’s sequence output to Time1 and Block 2.

The second problem concerns the Block 2 output connection to the Timer’s Time2 input. Since it is also connected to the inputs of Block 3 and 4, there is no guarantee which input operates first. This can cause a bad timing result.

A way you can revise the program to ensure correct propagation and accurate timing is shown below. Insert a Do object between Block 1 and Block 2 and connect the Block 2 sequence output to the Time2 input. The Do object forces the order in which objects operate as shown by the numbers surrounding it in the program.

The output pins on Block 2 operate in the order shown by the numbers around it. By connecting the Block 2 sequence output pin to the Time2 input, the Timer displays its result after Block 2 and all the blocks its output pin is driving have completed. Likewise, if there are other blocks connected to Block 2’s sequence output pin, insert another Do object to ensure correct propagation.

See Also

Error Handling, Capturing Control Pin Errors, Data Propagation on Control Pins, Building a Record, Multiple Inputs to a Formula


Understanding Data Containers

The propagation of data through a VEE program consists of the movement of data containers from one object to another. The data container is the VEE internal data format. Every data container has both a data type (text, real, and so forth), and a data shape (scalar, one-dimensional array, and so forth).

A data container may have only a single value in it, or it may have an array of several values. In either case, only one data container propagates from a particular data output pin when an object operates.

In the following example program, the Real64 constant object is configured as a one-dimensional array. The Int32 constant object is configured as a scalar.

As you might expect, when the program runs the Real64 constant object propagates a data container that is a one-dimensional real array. The Int32 constant object outputs a data container that is an integer scalar (the value 1). So how does VEE add these two containers? There is no problem -- VEE provides automatic data type conversion. VEE "promotes" the integer value 1 to become an equivalent real value (1.0). The a+b object then adds the real value 1.0 to every element in the one-dimensional real array, and outputs the resulting one-dimensional real array, as shown above.

If you are interested in the specific container that has been passed on any VEE data line, you can use Line Probe to look at that information. Move the mouse pointer over the desired line so the line is highlighted, and then click the left mouse button. The Container Information box appears. For example, the container passed on the data output line from the Real64 constant object of our example appears as follows.

In general, VEE converts data types automatically, and resolves data shapes if possible. You normally don't need to worry about how this is done. However, for technical information about the conversion process, refer to Converting Data Types on Input Terminals and Instrument I/O Data Type Conversions.

Terminal Information

Terminals show the object input type and shape requirements and display information about the input or output container. Pins are the connection points for terminals. You can display terminals if they are present but not visible; on the object menu, click Properties and check Show Terminals on the General tab.

To view or modify the attributes of a terminal, double-click on the terminal's information area (not the pin). You'll see a dialog box showing terminal information.

If all the fields in the dialog box are grayed out, the terminal cannot be modified. However if some of them are entry fields (white backgrounds) or buttons, you can change the values.

Terminals have the following characteristics:

Name is the name of terminal. You can usually modify this field. In formula expressions, the terminal name can be used in the equation.

Mode displays the terminal type, such as Data, Control, Trigger, or Error. You cannot modify this field.

Required Type and Required Shape (input terminals only) specify information about the input data that the object expects. On some objects, you can modify the Required Type or Shape, but you normally will not need to do this.

Container Information contains information about the container that the object will process (according to the input requirements on an input terminal) or has processed (on an output terminal). This information includes the data type, data shape, the size (if data is an array), any mappings, and the data itself.

See Also

Data Types, Data Shapes, Line Colors for Data Types


Data Types

VEE provides several data types that are used for all VEE operations. That is, every VEE data container sent between VEE objects is one of these types.

Note

If an input terminal on a VEE object specifies Any (the default in many cases), it will accept containers of any VEE data type.

Composite data types (Waveform, Spectrum, Record, Coord, and Object) are associated with particular data shapes.

Boolean is True or False.

UInt8 is an 8-bit two's complement unsigned integer (0 to 255).

UInt16 is a 16-bit two's complement integer (0 to 65535).

Int16 is a 16-bit two's complement integer (-32768 to 32767).

Int32 is a 32-bit two's complement integer (-2147483648 to 2147483647).

Int64 is a 64-bit two's complement integer (-9223372036854775808 to 9223372036854775807).

Real32 is a 32-bit real that conforms to the IEEE 754 standard (±3.40282347E±38).

Real64 is a 64-bit real that conforms to the IEEE 754 standard (approximately 16 significant decimal digits or ±1.7976931348623157E308).

PComplex is a magnitude and a phase component in the form (mag, @phase). Phase is in the currently active trigonometric units. For example, the PComplex number 4 at 30 degrees is represented as (4, @30) when Trig Mode is set to Degrees. Each component is Real64.

Complex is a rectangular or Cartesian complex number. Each complex number has a real and an imaginary component in the form (real,imag). Each component is Real64. For example, the complex number 1 +2i is represented as (1,2).

Waveform is a composite data type of time domain values that contains the Real64 values of evenly-spaced, linearly-mapped points and the total time span of the waveform. The data shape of a Waveform must be an Array 1D (a one-dimensional array).

Spectrum is a composite data type of frequency domain values that contains the PComplex values of points and the minimum and maximum frequency values. Spectrum allows the domain data to be uniformly mapped as log or linear. The data shape of a Spectrum must be an Array 1D.

Coord is a composite data type that contains at least two components in the form (x, y, ...). Each component is Real64. The data shape of a Coord must be a Scalar or an Array 1D.

Enum is a text string that has an associated integer value. The Enum data type is propagated by the objects found under Data [image] Selection Control (for example, the Radio Buttons object). You can access the integer value with these objects’ ordinal output pin, or by using the ordinal(x) function. The data shape of an Enum must be Scalar. Enum cannot be a required data input type.

Text is a string of alphanumeric characters.

Record is a data type composed of fields. Each field has a name and a container, which can be of any type (including Record), and a data shape of Scalar or 1D Array.

Object is a data type reserved for variables used for ActiveX Automation Objects and Controls when using VEE's execution mode. Objects can be passed as inputs to and outputs from UserObjects and UserFunctions, but not to remote UserFunctions nor compiled functions. An Object variable contains values for the name of the Dispatch interface, such as "Range" or "Application", and the pointer value of Dispatch, which are exported from an Automation Object. Object data shape must be Scalar.

Variant is not a distinct data type. It is used in expressions to indicate that the value it represents can be one of a number of other data types. It is the data type it holds at the moment.

For more information on data types and data type conversions, refer to Converting Data Types on Input Terminals and Instrument I/O Data Type Conversions.

For more information on Agilent VEE’s support of ActiveX Automation and Controls, see Help => Contents and Index => Tell Me About... => Active X.

Special Instrument I/O Data Types (VEE 5 and lower execution modes):

All integer values are stored and manipulated internally by VEE as the Int32 data type, and all real numbers are stored and manipulated as the Real (or Real64) data type. However, instruments generally support 16-bit integers or 8-bit bytes. Also, some instruments support a 32-bit real format. Therefore, VEE supports the following three data types, which are used only for I/O transactions involving instruments:

Byte is an 8-bit two's complement byte (-128 to 127). (Byte is used in READ BINARY, WRITE BINARY, and WRITE BYTE instrument I/O transactions. The WRITE BYTE transaction is used for specialized character output to GPIB instruments.)

Int16 is a 16-bit two's complement integer (-32768 to 32767).

Real32 is a 32-bit real that conforms to the IEEE 754 standard (±3.40282347E±38).

See Also

Understanding Data Containers, Data Shapes, Line Colors for Data Types


Line Colors for Data Types

In VEE 4 or higher Execution Modes, VEE assigns different colors to the data lines based on the type of data flowing through the line. Here are the default colors along with the names of the color properties (changeable via File [image] Default Preferences):

• Blue: numeric (Integer or Real type)

• Blue: complex (Complex and PComplex type)

• Orange: string (String type)

• Gray: sequence out (nil value, usually from a sequence out line)

• Black: unknown type or type that is not optimized (for example, Record types).

note

If the data type is an array, VEE displays a wider line. To increase speed, check your program for colored lines. The more non-black lines, the faster the program runs.

See Also

Understanding Data Containers, Data Types, Data Shapes


Data Shapes

Composite data types (Waveform, Spectrum, Record, Coord, and Object) are associated with particular data shapes:

The Waveform and Spectrum data types are always one-dimensional arrays.

The Record and Coord data types can be either scalars or one-dimensional arrays. (They cannot be arrays of two or more dimensions.)

The Object data type is always a scalar.

All other data types may have either a Scalar or an Array data shape:

Scalar is a single number such as 10 or (32, @10).

Array is an array with one to ten dimensions.

Arrays may be mapped. (A mapping is a set of continuous or discrete values that express the independent variables for an array.)

In many cases, a VEE object has data pins with an input data shape requirement of Any, meaning that the object accepts containers of more than one of the data shapes.

See Also

Understanding Data Containers, Data Types, Line Colors for Data Types


Converting Data Types on Input Terminals

In conventional programming languages, you manually convert between data types. VEE automatically converts between most data types.

Data shapes are not converted on input terminals, but data types and shapes may be automatically converted when used in math functions. Refer to Processing Data for further information.

Most objects accept any data type on their data input terminals, but a few objects require a particular data type or shape. For these objects, the data input terminal automatically attempts to convert the input container to the desired data type.

For example, a Magnitude Spectrum display needs Spectrum data. If the output of a Function Generator (a Waveform) is connected to the Magnitude Spectrum display, the input terminal of the Magnitude Spectrum automatically does an FFT to convert time-domain data to frequency-domain data (Waveform to a Spectrum).

The type conversion can be a promotion or demotion. A promotion is the conversion from a data type with less information to one with more. For example, a conversion from an Int32 to Real64 is a promotion. Such promotions take place automatically as needed -- you rarely need to be concerned with them.

A demotion is a conversion that loses data. For example, the conversion from a Real32 to an Int32 is a demotion because the fractional part of the Real32 number is lost. A demotion of data type occurs only if you force it by specifying a certain data type for an input on an object. Once you have specified a data type, the demotion will occur automatically if it is needed and is possible.

For example, if you change the input on a Formula object to Int32, and another object supplies a Real64 number to that input (such as 28.2), the value will be demoted to an Int32 (28).

To change the data type on the Formula input from Any to Int32, just double-click on the input terminal's information area (not the pin), and then click on the Required Type field. Click on Int32 in the drop-down list to change types.

Note

The conversion of data types for instrument I/O transactions in VEE 5 and prior execution modes is a special case. Refer to Instrument I/O Data Type Conversions for further information.

The Record data type has the highest priority. However, VEE does not automatically promote to or demote from the Record data type. To convert between Record and non-Record data, use Build Record and Unbuild Record. For further information, refer to Using Records and Using DataSets.

The Object data type also has no automatic promotion or demotion, and it cannot be converted to other data types. ActiveX automation objects use the Object data type. You can create and use automation objects by using the functions CreateObject and GetObject.

When the conversion cannot be done, VEE returns an error. The following table shows when conversion is automatic "yes" or when VEE returns an error "no".

When selecting "Any" for the data shape or type, be aware that "Any" means no conversions and no checking. Null (nil) cannot be converted to a data type, but can be passed when the terminal is set to Any Shape and Any Type. This is true for all VEE objects.

The behavior of nil on a data input changed in VEE 7.03 and later. This refers specifically to nil data sent into an input terminal with data type or shape constraints set to anything other than "Any". If an input terminal has its data shape and or type constraint set to other than Any, the behavior changed in VEE 7.03. Before VEE 7.03, the nil would be passed through even if the input terminal required say an Int32 scalar. In VEE 7.03 and later, an error appears if the input terminal constraints are set and a nil is passed in.

Table: Promotion and (Demotion) of Types in Input Terminals

To: From: | Boolean | UInt8 UInt16 Int16 Int32 Int64 | Real32 Real64 | Complex | PComplex | Waveform | Spectrum | Coord | Enum | Text
Boolean | n/a | yes | yes | no | no | no | no | no | no | yes
UInt8 UInt16 Int16 Int32 Int64 | yes | (yes)[3] | yes | yes[1] | yes[1] | no | no | yes[2] | no | yes
Real32 Real64 | yes | (yes)[3] | (yes)[3] | yes[1] | yes[1] | no | no | yes[2] | no | yes
Complex | no | no | no[4] | n/a | yes | no | no | no | no | yes
PComplex | no | no | no[4] | yes | n/a | no | no | no | no | yes
Waveform | no | (yes)[3] | (yes)[8] | no | no | n/a | yes[5] | yes | no | yes
Spectrum | no | no | no | (yes)[8] | (yes)[8] | yes[5] | n/a | no | no | yes
Coord | no | no | no | no | no | no | no | n/a | no | yes
Enum | no | no[6] | no | no | no | no | no | no | n/a | yes
Text | yes[9] | (yes)[7] | (yes)[7] | (yes)[7] | (yes)[7] | no | no | (yes)[7] | no | n/a

Table Notes:

yes = A promotion

(yes) = A demotion

n/a = Not applicable

[1] An integer or real value promotes to Complex (value, 0) or to PComplex (value, @0).

[2] The independent component(s), which are the first n-1 field(s) of an n-field Coord, are the array indexes of the value unless the array is mapped. If the array is mapped, the independent component(s) are derived from the mappings of each dimension. The dependent component, y, is the array element. If the container is a Scalar (non-array), conversion fails with an error.

[3] These demotions will cause an error if the value is out of range for the destination type.

[4] This demotion is not done automatically, but can be done with the re(x), im(x), mag(x), and phase(x) objects or the Data [image] Build Data/UnBuild Data [image] objects.

[5] An FFT or inverse FFT is automatically done.

[6] This demotion is not done automatically, but can be done with the ordinal(x) object.

[7] This demotion causes an error if the text value is not a number (such as 34 or 42.6) or is not in an acceptable numerical format. The acceptable formats are as follows (spaces, except within each number, are ignored):

Text that is demoted to an integer or real type may also include:

A preceding sign. For example, -34.

A suffix of e or E followed by an optional sign or space and an integer. For example, 42.6E-3.

Text demoted to Complex must be in the following format: (number, number).

Text demoted to PComplex must be in the following format: (number, @number). The phase (the second component) is considered to be radians for this conversion, regardless of the Trig Mode setting.

Text demoted to a Coord type must be in the following format: (number, number, ...).

[8] These demotions keep the Waveform and Spectrum mappings.

[9] Only can convert "True" and "False".

See Also

Instrument I/O Data Type Conversions, Converting Data Types with Objects and Functions


Converting Data Types with Objects and Functions

VEE provides objects and built-in functions that convert data from one type to another. These are available to handle special type conversions that VEE cannot handle on its input terminals.

The type conversion functions built into VEE can be added to a program by using the Function & Object Browser, or by entering the function name into any object that accepts expressions. In the Browser, select Built-in => Type Conversion for the available functions.

  • As an example, the function asText(x) converts the input x to the data type Text and returns the same data shape as x. x can be any shape and any type. In the expression asText(3.4), the result is the Text value "3.4".

note

Prior to VEE 5.0, an Integer was converted to a Real when it was entered directly into expressions in an object such as Formula. In VEE 5.0 and later, an Integer in an expression is no longer converted to a Real when the Execution Mode is set to VEE 5 or higher. This change does not affect data type conversions on input terminals. For example, the Formula expression “2^4” will produce the Real64 value 16.0 in VEE 4 and prior modes, but the Int32 value 16 in VEE 5 and higher modes.

The Record data type has the highest priority. However, VEE does not automatically promote to or demote from the Record data type. To convert between Record and non-Record data, use the objects Build Record and Unbuild Record.

Similar results are possible in expressions using syntax described in Using_records.

The Coord data type has some special rules associated with it:

• Although arrays of Int32 and Real data types can be promoted to Coord, a Coord cannot be converted to any other numeric type.

• When unmapped arrays are converted to Coord, the independent Coord values (the first Coord fields) are created from the array indexes while the dependent Coord value (the last Coord field) contains the element value. For example, if array A is converted to a Coord and A contains [1,5,7], it is converted to a Coord array with [(0,1),(1,5),(2,7)] in it.

• When mapped arrays are converted to Coord, the independent Coord parameter ranges from the low value of the mapping to the value Xmin+(Xmax-Xmin/N)*(N-1).

The Object data type also has no automatic promotion or demotion and it cannot be converted to other data types. ActiveX automation objects use the Object data type. You can create and use automation objects by using the functions CreateObject and GetObject. For more information about VEE support for ActiveX Automation and Controls, see Using ActiveX Automation in VEE.

See Also

Help => Index and contents => Tell me about... => Active X

Converting Data Types on Input Terminals, Instrument I/O Data Type Conversions


Processing Data

To process data, you operate on it with math functions available in the Function & Object Browser. Use the Function & Object Browser toolbar button to open the browser. You can combine the functions to create mathematical expressions.

Note

You can also process data before running a program by using numeric entry fields such as those in Constant objects. Numeric entry fields on some objects support the use of arbitrary formulas. The formula is immediately evaluated; the resulting value is used for the field. You cannot use variables in Constants. Also, the typed-in formula must evaluate to a scalar value of the proper type or of a type that can be converted to that which the object expects. In general, you can use any of the dyadic operators, parentheses for nesting, function calls, and the predefined numeric constant PI (3.1416...) in numeric entry fields.

The Function & Object Browser contains a set of mathematical functions to process your data in numerous ways. Each of these functions are expressions entered in a Formula object with the corresponding title, inputs, and outputs. You can change the expressions in the open view of each Formula object, and change their properties, too. All the functions that are listed in the Function & Object Browser can be used in any object in other menus that allow expressions. The objects in other menus that allow expressions are:

Data [image] Access Array [image] Set Values

Data [image] Access Array [image] Get Values

Data [image] Access Record [image] Get Field

Data [image] Access Record [image] Set Field

Device [image] Sequencer

Flow [image] If/Then/Else

Flow [image] Conditional (all conditional objects)

I/O objects that use transactions

Expressions may contain the names of data input terminals, data output terminals (I/O transactions and Formulas only), variables (global and declared), user-defined functions (compiled, remote, and UserFunctions), and any mathematical expression from the Function & Object Browser. Data input terminal names are used as variables. VEE is not case sensitive about names of input variables within expressions for USASCII keyboards. For non-USASCII keyboards, VEE is case insensitive for 7-bit ASCII characters only. Expressions are evaluated at run-time.

See Also

General Concepts, Using Assignment Operations, Using Dyadic Operators


General Concepts

If you pass an array to a function, the function operates on each element of the array, unless stated otherwise. For example, sqrt of a scalar returns a scalar; sqrt(4) returns 2. But sqrt of an array returns an array of the same size; sqrt([1,4,9,64]) returns the array [1,2,3,8].

In VEE 5 and higher execution modes, all numbers in an expression field without a decimal point or "E" exponent are considered to be Int32. In VEE 4 and VEE 3 modes, all numbers are considered Real64 values, unless you use parentheses to specify Complex or PComplex values. Therefore, 2 is considered to be a Real64 or an Int32, depending on the execution mode of your program. (1, @2) is a PComplex number, while (1, 2) is a rectangular Complex number. 1.0 and 1E3 are always Real64.

Note

VEE interprets multiple values contained within parentheses as a Complex or PComplex value. If you need to use a Coord value in an expression, use the coord(x, y) function. The coord function takes 2 or more parameters. coord(1, 2) returns a Scalar Coord container with two fields.

All functions that operate on Coord data operate only on the dependent (last) field of each Coord. For example, abs(coord(-1, -2, -3)) returns the Coord (-1, -2, 3).

An Enum container is always converted to Text before every math operation except the function ordinal(x). Enum arrays are not supported. If you try to create an Enum array, a Text array is created instead.

For information on specific data type definitions, refer to Data Types.

Using Strings in Expressions

Strings within expressions must be surrounded by double quotes. You may use the following escape sequences within strings:

________________________________________

Escape Character

Meaning

________________________________________

\n | Newline
\t | Horizontal Tab
\v | Vertical Tab
\b | Backspace
\r | Carriage Return
\f | Form Feed
\" | Double Quote
\’ | Single Quote
\\ | Backslash
\ddd | Character Value. d is an octal digit.

________________________________________

Using Arrays in Expressions

Arrays in expressions can be used just like scalars, just refer to them by their name. Array constants can be entered directly into an expression (such as [1,2,3]). Arrays used in functions, like sin([1,2,3]), have the sin function applied to every element of the array. VEE requires commas between array elements.

Note

Array indices are 0-based. The indices start with zero and continue to n-1, where n is the number of elements in that particular dimension.

You can use expressions to access portions of an array. Once you've specified the sub-array in the expression, you can output the sub-array, or use it in further expression calculations.

You can access only contiguous sub-arrays from each array. To access sub-arrays, you must specify a parameter for each dimension in the array.

Use the following characters to specify array parameters:

The comma "," separates array dimensions. Each sub-array operation must have exactly one specification for each array dimension.

The colon ":" specifies a range of elements from one of the array dimensions.

The asterisk "*" is a wildcard to specify all elements from that particular array dimension.

Note

Waveform time spans, Spectrum frequency spans, and array mappings are adjusted according to the number of points in the sub-array. For example, if you have a 256 point Waveform (WF) and you ask for WF[0:127], you'll get the first half of the Waveform and a time span that is half of the old one.

Examples

A is an Array 1D, 10 elements long.

A[1] accesses the second element in A and outputs a scalar.

A[0:5] returns a one-dimensional sub-array that contains the first 6 elements of A.

A[1:1] returns a one-dimensional sub-array that contains one element, which is the second element of A. Note the difference between this and the first example, A[1].

A[2:*] returns a one-dimensional sub-array that contains the third through the tenth elements of A.

A or A[*] returns the entire array A.

A[1,2] returns an error because it specifies parameters for a two-dimensional array.

B is a 5x5 matrix (an Array 2D).

B[*] returns an error because it specifies only one parameter, and B is a two-dimensional array.

B[1,2] returns a scalar value from the second row, third element.

B[1,*] returns all of row one as an Array 1D.

B[1,1:*] returns all of row one, except for the first element, as an Array 1D.

B[4,1:4] returns an Array 1D that contains four elements: the second through fifth values from row 4.

B[5,5] returns an error because arrays are zero-based. The array can only be accessed through B[4,4].

B[1 1] returns an error because a comma must separate the dimension specifiers.

Building Arrays in Expressions

You can build an array from elements of other arrays or sub-arrays. Each element in the expression must specify the same number of dimensions and contain the same number of values in each dimension.

Examples

A is an Array 1D with ten elements. B is a 5x5 matrix.

[1,2,3] returns a three element Real Array 1D that contains the values 1, 2, and 3.

[A[0], A[5:7], A[9]] causes an error because both scalar and Array 1D elements are specified.

[A[0:4], B[0,*]] returns a ten element Array 2D (of size 2 by 5) that contains the first five elements from A as the first row and the first row from B as the second row.

[A[0], A[1], B[2,3], A[5]] returns a four element Array 1D that contains the first and second element of A, the element from the third row and fourth column of B, and the sixth element of A.

Using Variables in Expressions

You can create and set variables by using the Declare Variable and Set Variable objects, and you can access variables by using the Get Variable object. Refer to Declare Variable, Set Variable, and Get Variable for further information.

In addition, you can access a variable by including its name in a mathematical expression. You can include a variable in a mathematical expression in a Formula object, or in any object with a delayed-evaluation expression field. These objects include If/Then/Else, Get Values, Get Field, Set Field, and all devices using expressions in transactions, including To File, From File, From DataSet, From Stdin, To/From Socket, Sequencer, and Direct I/O.

To include a variable in an expression, just use the variable name as if it were an input variable. For example, suppose a program uses a Set Variable object to define the variable numFiles. Elsewhere in the program, a Formula object with input A may use the expression numFiles+3*A.

Note

Variable names are case-insensitive. Either upper-case or lower-case letters may be used. Thus, GLOBALA is equivalent to globalA.

To avoid errors or unexpected results, you should be aware of two limitations when you include variables in an expression:

1. Local input variables have higher precedence than global variables. This means that, in case of duplicate variable names, the local variable is chosen over the global variable. For example, if the expression Freq*10 is included in a Formula object that has a Freq input (a local variable), and there is also a global variable named Freq, the expression will be evaluated with the local variable Freq, not the global one. No error will be reported regarding this duplication.

2. Depending on the flow of your program, an object that evaluates an expression containing a variable may execute before the variable is defined. For example, suppose the variable globalA is set with a Set Variable object, and the expression globalA*X^2 is included in a Formula object. Depending on the flow of your program, the Formula object may execute before the Set Variable object executes. In this case, the Formula object won't be able to evaluate the expression because globalA is undefined. An error message will appear.

It is important that you take steps to ensure correct propagation -- that Set Variable executes first. You can do this by connecting the sequence output pin of the Set Variable object to the sequence input pin of the Formula object in this case, or of any other object that includes the variable in an expression to be evaluated. If a Get Variable object is used, its sequence input pin should also be connected to the sequence output pin of Set Variable. Also, if you declare a variable using the Declare Variable object, you must initialize it using Set Variable. For further information, refer to About Variables.

Note

By default, Delete Variables at PreRun in the Default Preferences dialog box is checked (enabled), so values are deleted from variables when you run a program. This prevents variables from containing "old" data and causing unexpected results.

Variables can be arrays. Just access a variable array as if it were an input variable using array syntax, for example: GlobAry[2]. If a variable is a Record, use the record access syntax, such as globRecord.numFiles.

Using Records in Expressions

You can use expressions to access a field or sub-field of a record. Use the A.B sub-field syntax to access the B field of a record A. If A is a record with a field B, which itself is a record which has a field C, you may use the A.B syntax recursively to access the C field. That is, use the expression A.B.C. If A does not have a B field, or B does not have a C field, an error will result.

There is no limit on the number of recursions of A.B.C.D.E.F that may be used in expressions. Note that field names are not case sensitive (lowercase and uppercase letters are equivalent). Field names may be duplicated in sub-Records, so you may use the expression A.a.A.

Records are very useful as variables, so that one variable may hold several different values. Note that a Formula object can be used in place of a Get Variable. Thus, you can accomplish the GlobRec.numFiles access in one object, instead of using both a Get Variable and a Formula object to unbuild the record.

The record and array syntax may be combined in expressions to access a field of a record array (for example A[1].B), or to access a portion of an array that is a field of a record (for example, A.B[1]). Note the difference between A[1].b and A.b[1] (both are supported):

You would use the first for a record 1D with a field b. A[1].b accesses the field b of the second record element of the record array A.

You would use the second for a scalar record with a field b, which is a 1D array. A.b[1] accesses the second element of the field b of the record A.

To change a field in a record, use the assignment operator in a Formula object. For example, suppose you have a record R with a field A, and you wish to change the value of R.A to be sin(R.A). Just change the expression to R.A = sin(R.A). You can continue to use the record R (with the new value for field A) later in your VEE program.

Note

For information about using Objects in expressions to manipulate ActiveX automation objects and controls, see Using ActiveX Automation in VEE and Using an ActiveX Control in VEE.

See Also

Processing Data, Using Assignment Operations, Using Dyadic Operators


Using Assignment Operations

The Formula object allows expressions that use assignment operations to change values in parts of arrays and records, and assign values to local and global variables. The Result output terminal contains that part of the array or record that changed, not the entire array or record. For example, in a Formula with the expression A[2] = 4 the Result terminal contains array element A[2] with a value of 4. It does not contain all of array A. Formula objects preset with assignments are available in the Function & Object Browser => Operators => Assignment.

Note

Assignment operations are allowed only in Formula objects.

Allowed Syntax

Multiple expressions, separated by semi-colons, are allowed in Formulas. The left-hand side of expressions allow syntax that change the values for array and record elements, and for variables. The right-hand side must match exactly the part of the left-hand side that is being modified. For records, the schema (a field's type, shape, or size) cannot be changed, only its values. The following examples show left-hand syntax that works for arrays:

A[2]=
A[2, 3, 4:5]=
A[2:4, 4:6, 3:*, *]=

The following examples show left-hand syntax that works for records:

RecA.B=
RecA.B.C.D=
RecA[1].B=
RecA.B[1]=
RecA.B.C.D[1]=
RecA[1].B[2].C[3].D=
RecA.B[2:3].C[3:4]=

The following left-hand syntax is allowed to directly set global and local variables, and initialize declared local variables:

GLOBAL=2
TMP_LOCAL=4

Here are examples of assignments showing how the right-hand-side must match the part of the left-hand-side that is being modified. The data type of the right-hand side must be coercible to the data type of the left-hand side, such as integer to real or real to String. A coercion such as Complex to real cannot be done.

ArrayA[2:4] = ArrayB (ArrayB must be a one-dimensional array with three elements.)

ArrayA[2, 3, 4:5, 7, 8:9] = ArrayB (ArrayB must be a two-dimensional array, of size 2 by 2.)

Rec[3:4].field = ArrayB (ArrayB must be a one-dimensional array with two elements.)

Rec[3:4].field[4:5] = ArrayB (ArrayB must be a two-dimensional array, of size 2 by 2.)

Non-explicit use of arrays of records on the left-hand side of assignments is not allowed. If Rec is an array of records, the expression Rec.A=2 will cause an error, prompting a request that you use the full explicit syntax, Rec[*].A=2. A similar error results with Rec.B=2 if Rec is a scalar record, and B is an array; the resulting prompt will request that you use the explicit Rec.B[*]=2.

Note

In VEE 4.0 and later versions, the Set Values and Set Field objects are actually Formula objects with assignment expressions. These objects have been changed from their definitions in prior versions of VEE. Existing programs written with VEE 3.x and older, that use the Set Values and Set Field objects will retain the prior definition.

Global and Local Variables in Assignments

Assignments in Formula objects can change values in global and local variables with expressions such as A=2 or GlobalA[5]=2. Since variables can be undeclared globals, declared globals or locals, or directly-set locals, the Formula object will look for the variable A using the following order of precedence:

1. A local variable which is an input terminal. This overwrites the input terminal value, including its type and shape.

2. A local variable which is an output terminal. This variable is created and placed on the output terminal.

3. A global variable. The variable must already exist. Its value is completely changed, including its type and shape.

Given these rules, an error results if Formula contains an assignment such as tmp=2 where tmp does not meet one of these criteria.

Assigning values to global arrays and records requires added attention since these variables may be undeclared or declared. A global exists when it is created using an object such as Set Variable, or when it is declared using Declare Variable. For an undeclared global, its type and shape can be changed by an assignment expression; however, for a declared global, the right-hand side of the assignment must be coercible to the global’s declared type.

Very Important!

When you declare a global array or record variable using the Declare Variable object, the entire variable must be initialized collectively before you can change part of the global. The following figure shows the variable GlobalAry declared and initialized before an individual part is changed by the assignment in Formula.

Data Container Contents on Terminals

Formula object input and output terminals affect how the values for variables are changed by assignments. The data container on the Result output terminal contains the modified part of an assignment expression’s left-hand side, including any changes to the data type and shape. In a Formula with the expression ArrayA[2:4] = ArrayB[5:6], the Result output terminal contains ArrayA[2:4] with the values from ArrayB[5:6]. In an expression such as ArrayA[2]=4 where the ArrayA data type is Complex, the value for ArrayA[2] in the output terminal is converted to Complex (4,0).

The following output terminal names can be used:

Result is the default output terminal on Formula. It is a reserved name, and contains the result of an assignment expression. You can delete Result to use other outputs, then add it back if needed, but you cannot rename an output terminal Result.

An input terminal name. This value is copied from the input. If changed in an assignment, the new value is used on the output. The variable must exist and have a value before it can be used as an input terminal name.

A local variable name such as tmp that is created by an assignment expression such as tmp=2.

You can use additional output pins on a Formula to get various parts of a modified array or record out of the object. This lets you pass the modified part of a variable out one terminal and pass the whole variable out another terminal. To get the whole array or record on the output terminal, use a global variable in an assignment expression or add an output terminal to the Formula object for the array or record. If an output terminal exists that does not get a value assigned, an error occurs.

Mappings on arrays are ignored unless the entire container is modified. For example, ArrayA[2:4] = ArrayB[2:4] does not modify the mappings on ArrayA. But A = ArrayB[2:4] will set the mappings on A since it is replaced by ArrayB.

Error Recovery

Since a Formula can contain a series of expressions including assignments and other operations, errors are handled in certain ways. If an assignment or other operation is done, then a following expression errors, previous expressions are not undone. Consider the expressions Global[2]=24; 2/0 in a Formula. Global[2] is set to 24, then the division by zero causes an error. VEE will not set Global[2] back to its previous value.

Note

For procedures about using assignment operations, see Help [image] Contents [image] How Do I … Work with Data section, then look at the topics under Working with Arrays (such as To Change Values in an Array), and at topics under Working with Variables.

See Also

Using ActiveX Automation in VEE, Using an ActiveX Control in VEE

Processing Data, General Concepts, Using Dyadic Operators


Using Dyadic Operators

The set of dyadic operators have several additional conditions and guidelines. The dyadic operators are visible in the following categories of the Function & Object Browser in Operators:

Arithmetic

a + b

a - b

a * b

a / b

a ^ b (exponentiation)

a mod b (modulo - returns remainder of division)

a div b (integer division - no remainder)

Comparison

a ~= b

a == b

a != b

a < b

a > b

a <= b

a >= b

Logical

a AND b

a OR b

a XOR b

NOT a (a monadic that follows the same guidelines as dyadics)

When using dyadic operators on arrays, the array size, array shape, and array mappings (if they exist) must match. For Coords, the values of the independent variable for each Coord must match.

Precedence of Dyadic Operators

This list is the order of precedence of the dyadic operators. They are listed from highest to lowest, with operators of the same precedence listed on the same level.

1. parentheses ( and ) used to group expressions

2. ^

3. unary minus -

4. * / MOD DIV

5. + -

6. ~= == != < > <= >=

7. NOT

8. AND

9. OR XOR

Data Type Conversion

For the dyadic operators, the input values are promoted to the highest data type and then the operation is performed. The data type of the output is the highest input data type. For example, when the complex number (2, 3) is added to the String "Dog", "Dog"+(2,3), the result is the String "Dog(2, 3)".

Note

There is one exception to this rule. When you multiply a Text string by an Int32, the result is a repeated string. For example, "Hello"*3 returns HelloHelloHello. No data type promotion occurs in this case.

The data type order (from highest to lowest) is:

1. Object

2. Record

3. Text (Enum is treated as Text)

4. Spectrum

5. PComplex

6. Complex

7. Coord (no conversion to any other numeric type possible)

8. Waveform

9. Real64

10. Real32

11. Int64

12. Int32

13. Int16/UInt16

14. UInt8

15. Boolean

16. Variant

The Variant data type is not "fixed" as a specific kind of data. It can be one of the other data types as needed.

Object Considerations: Objects will not automatically demote to other types. No dyadic operations are supported on Objects themselves, but since most Objects have a default property which is a String or Integer value, most operations can be performed on Objects. The difference is that you end up performing the operation on the default property. For more information about Objects and their use with ActiveX automation in VEE, see Using ActiveX Automation in VEE and Using an ActiveX Control in VEE.

Record Considerations: Records have the highest precedence of all data types, but other data types can be converted to the Record data type only by using special objects such as Build Record. Records will not automatically demote to other types, nor will other types automatically promote to the Record type.

The dyadic operators do support combining records and other data types, but they will always return a record in this case. A dyadic operation on a record and non-record will apply the operation with the non-record to every field of the record. For example, consider a record R with two fields A, a scalar real value (2.0), and B, a scalar Complex value (3,30). The expression R+2 will produce a record R with two fields A, a scalar real with value 4, and B, a scalar Complex with value (5,30). If the operation cannot be performed on every field in the record, an error occurs.

Dyadic operations on a record and any other type will return a record with the same "schema," so the resulting record will have the same fields with the same names, types, and shapes. The dyadic operation may not change the type or shape of a field of a record. For example, consider a record R with two fields A, a scalar real, and B, a scalar Complex. The expression R+(2,3) will cause an error. VEE will first try to add (2,3) to R.A, then do the same with R.B. The error occurs because the R.A field is a real and the result of R.A+(2,3) would be a Complex. The Complex cannot be demoted to a real to be stored back into R.A.

Dyadic operations on records using arrays treat the record as having higher precedence than the array. For example, [1,2,3] + [3,4,5] produces [4,6,8], so the arrays are combined piece by piece. But records have higher precedence than arrays. This means that if R is a record with two fields A and B, the expression R + [1,2] will try to add the array [1,2] to each field of R. It will not add 1 to R.A, and 2 to R.B.

Things get even more complicated when you combine arrays with record arrays. For example, suppose R is a record 1D array, two long, with three fields A, B, and C. The expression R + [1,2,3], or the expression R + [1,2] will add the entire array to each field A, B, and C for every element of R. Even though R is an array, the fact that it is a record is more important.

A dyadic operation on two records will combine them field by field, so the two records must have the same "schema." That is, each record must have the same number of fields, and each field must have the same name, type and shape, in the same order.

If you want to add 1 to field A, add 2 to field B, and so forth, the easiest way is to use multiple assignments (see Assignment). In a Formula object, enter the expression R.A=R.A+1,R.B=R.B+2. You can then use R.A and R.B with their new values in your program.

Coord Considerations: The Coord data type has some special rules associated with it:

Although arrays of integer and real data types can be promoted to Coord, a Coord cannot be converted to any other numeric type.

When unmapped arrays are converted to Coord, the independent Coord values (the first Coord fields) are created from the array indexes; the dependent Coord value (the last Coord field) contains the element value. For example, if array A is converted to a Coord and A contains [1,5,7], it is converted to a Coord array with [(0,1),(1,5),(2,7)] in it.

When mapped arrays are converted to Coord, the independent Coord parameter ranges from the low value of the mapping to the value Xmin+(Xmax-Xmin/N)*(N-1).

Spectrum Considerations: If you choose to use dB scaling, you must keep track of it yourself. Although dB-scaled data displays correctly (except on the Waveform (Time) display), many math functions such as fft(x), ifft(x), and those involving PComplex numbers don't operate correctly on dB-scaled data. If you need to use these operations, convert the dB-scaled data to linear scaling before operating on it.

When you are using particular dB units, some math functions give meaningful results, but only within the confines of those units. For example, if you add 20 to a dBW-scaled Spectrum, 20 is added to the magnitude of each element (which has the same effect as converting the Spectrum to a linear scale, multiplying each element by 100, and converting back to dBW).

Int16 and UInt16 Considerations: UInt16 is not a subset of Int16 and vice versa. In order to support operations between UInt16 and Int16, the rule is to promote the two data types into higher data type -- Int32 first, then do the operations. The result of the operation will be of Int32 type.

Variant Considerations: The result of dyadic (+-*/, etc.) evaluations and functions cannot be a Variant

In the expression b=a, b will be the same type as a, even if it was a Variant.

In the expression b=a+2, b will never be a Variant, regardless of what a is.

In the expression b=sin(a), b will never be a Variant, regardless of what a is.

The function func(2+a) will always be sent a non-Variant, regardless of what a is.

The function func(a) will be sent a Variant if a is a Variant.

Just a variable name a, a monadic operator -a, or parentheses (a) will not change the data type of a.

Data Shape Considerations

For dyadic operations where both operands (inputs) are arrays, the size and shape of the arrays must match. The result of the operation is an array with the same size and shape as the input arrays, except for the relational operators (==, <, and so on, which always return a scalar.) If arrays have a different number of dimensions or are of different sizes, VEE returns an error. For example, [1,2] + [1,2,3] returns an error.

If you are operating on a scalar and an array, the scalar is treated as if it were a constant array of the same size and shape as the array operand. For example, 2 + [1,2,3] is treated as [2,2,2] + [1,2,3]. The result is [3,4,5].

When an n-dimensional array is converted to a Coord, the Coord data shape is an Array 1D with n+1 fields in each Coord element.

See Also

Processing Data, General Concepts, Using Assignment Operations


Displaying Test Data

Following table describes the display capabilities for the different VEE objects.

Display | Description
Alphanumeric | Displays values as text or numbers. Requires SCALAR, ARRAY 1D, or ARRAY 2D.
Beep | Gives an audible tone to highlight a place in your program.
Complex Plane | Displays Complex, Polar Complex (PComplex), or Coord data values on a Real vs. Imaginary axis.
Indicator => Meter, Thermometer, Fill Bar, Tank, Color Alarm | All of these indicators display numbers with a graphical representation suggested by their names. They all have color-coded ranges - usually three, but the meter has five. The Color Alarm can simulate an LED with a text message flashing up on the alarm in each range.
Label | An object used to put a text label on the Panel View. The colors and fonts may be easily adjusted through Properties... in the object menu while in the Panel View.
Logging Alphanumeric | Displays values as text or numbers when repeatedly logged. Requires SCALAR or ARRAY 1D.
Note Pad | Uses a text note to clarify a program.
Picture (PC) | An object used to put a graphic image on the Panel View. The formats supported are: *.BMP (bitmaps), *.GIF (GIF87a and GIF89), *.JPEG, *.PNG, and *.WMF (Windows Meta File)
Polar Plot | Graphically displays data on a polar scale when separate information is available for radius and angle data.
Spectrum (Freq) | A menu that contains frequency domain displays: Magnitude Spectrum, Phase Spectrum, Magnitude vs. Phase (Polar), and Magnitude vs. Phase (Smith). Inputs must be Waveform, Spectrum, or an array of Coords. Waveform inputs are automatically changed to the frequency domain with a Fast Fourier Transform (fft).
Strip Chart | Graphically displays the recent history of data that is continuously generated while the program runs. For each y input value, the x value is incremented by a specified Step size. When new data runs off the right side of the display, the display automatically scrolls to show you the latest data.
Waveform (Time) | Graphically displays Waveforms or Spectrums in the real time domain. Spectrums are automatically converted to the time domain using an Inverse Fast Fourier Transform (ifft). The x axis is the sampling units of the input waveform.
X vs. Y Plot | Graphically displays values when separate data information is available for X and Y data.
XY Trace | Graphically displays mapped arrays or a set of values when y data is generated with evenly-spaced x values. The x value that is automatically generated depends on the data type of the trace data. For example, a Real trace would generate evenly-spaced Real x values; whereas, a Waveform trace would generate x values for time.


About Variables

There are two types of variables in VEE: undeclared and declared. Both types of variables can contain any data type, including complex data types such as waveforms and records. They can also be any data shape, including scalars and arrays.

About Undeclared Variables

Undeclared variables are the easiest to use but execute slower and do not allow scoping (described in About Declared Variables, below). Undeclared variables include the following:

• Global variables that can be used anywhere in the program. They are created with the Set Variable object. They are deleted before the program is run if the Delete Variables at PreRun property is set. Global variables must be created before they can be accessed via the Get Variable object or used in expressions, or else your program will generate an error.

Undeclared global variables are useful if you do not know what data type or shape your values will be or if the values may change type or shape. If you want a scoped variable (i.e., local), use declared variables (see “About Declared Variables").

• Temporary variables that are used only in Formula objects. You can create a temporary variable, such as tmp, in a Formula by adding an output terminal. For example, to swap the values input in a Formula object’s terminals a and b, use the temporary variable tmp. The expression would look like tmp=a, a=b, b=tmp. For more information about temporary variables, see Assignment.

• Terminal names that are used as variables within objects (such as in transaction or Formula objects).

About Declared Variables

Declared variables are defined before they are used. They have the additional feature of scoping and allow VEE to run faster because the data type and shape are known before run time. However, if you attempt to set a declared variable with values that are different from the data type or shape of the values set in the declaration, the program will error.

To declare a variable, use the Data Þ Variable Þ Declare Variable object. When placed in a context, it declares the variable before any of the other objects execute. When the variable has been declared, it has no value until it is set via a Set Variable or a Formula object.

The scope of a declared variable must be specified in the Declare Variable object. The scopings are as follows:

• Global - The variable can be used anywhere in the program.

• Local to Context - The variable can only be used in a single UserObject or UserFunction, or in Main. This variable can be used in the context that the Declare Variable object is in and in UserObjects nested inside the context. The variable cannot be used in UserFunctions called from the context.

• Local to Library - The variable can only be used within the library of UserFunctions where the Declare Variable object is used. Declare Variable must be located in one of the UserFunctions.

You cannot define multiple variables with the same name and scope. If this happens, you will get an error.

About Variables Naming

You can use any valid variable name for a variable. The first character must be a letter. Letters, numbers, and the underscore character may be used in the rest of the name. Variable names are not case sensitive (uppercase and lowercase letters are equivalent). Special characters, including spaces, are not allowed.

To retrieve the value of the variable, you must use the name that you specified when the variable was declared or set.

When Execution Mode in Default Preferences is set to VEE 5 mode or higher, some names must be unique. When Execution Mode is set to VEE 4 or VEE 3 mode the question of precedence arises when you have named a variable the same name as another variable. The order of precedence (from highest to lowest) is:

1 Input terminal name (such as in a Formula or a transaction object)

2 Temporary variable (as in a Formula object)

3 Local to Context declared variable

4 Local to Library declared variable

5 Global declared variable

6 Global undeclared variable

If two variables with the same name are in an object, there is a conflict. The variable with the highest precedence is used.

See Also

Execution Modes, To Create a Variable, To Use a Variable, Accessing Variable Values, Setting Initial Values, Using Variables in Libraries


Defining an Agilent VEE Function

Overview of User-Defined Functions

There are three types of user-defined functions in VEE. The overview of each type of function is as follows:

1 UserFunctions

• To create a UserFunction, you select Device [image] UserFunction, or click Edit [image] Create UserFunction with several objects selected.

• To call a UserFunction from different places in a program, you use the Call myFunction (Device [image] Call) object or use an expression within an object (from Formula, for example). You can also generate call objects in the Main program from the UserFunction, using the UserFunction object menu and selecting choices such as Generate [image] Call.

• To edit a UserFunction , you click on Edit [image] Edit UserFunction... and select the appropriate UserFunction from the list box presented.

• To transfer UserFunctions from one program to another, you merge the UserFunctions during program development or import them at runtime (Device [image] Import Library).

2 Compiled Functions

• To create a compiled function, you work outside of VEE using a compiled language. You then put the functions into a library, such as a DLL.

• To link a compiled function to a program, you use the Import Library object, which links the library to VEE at run time. (For a more detailed discussion, refer to “Optimizing Agilent VEE Programs).

• To call a compiled function, you use the Call myFunction object or write an expression within a VEE object.

3 Remote Functions

• Similar to UserFunctions, except that they run on a remote host computer connected on your network.

See Also

Finding Functions in Large Programs


About UserFunctions

A UserFunction is specifically designed for creating a user-defined function. You create a UserFunction by selecting it from the Device menu or by converting existing objects or an existing UserObject into a UserFunction.

You can call your UserFunction using a Call object in your program (Device Þ Call) or other objects identified below. A UserFunction can be saved in a library and imported into a program with the Import Library object.

The advantage of creating a UserFunction over using a UserObject is that you can call a single UserFunction several times in your program. Thus, there is only one UserFunction to edit and maintain, rather than several instances of a UserObject.

When executed in VEE 4, or higher Execution Mode, a UserFunction will time-slice when called from Call, Formula, If/Then/Else, or Sequencer objects (only from the Function field).

A UserFunction will not time-slice when called from a To File, To String, or similar object or if the Formula object’s formula is supplied via a control pin.

The Differences Between UserObjects and UserFunctions

The reason that VEE provides both UserObject and UserFunction is because the two have different characteristics and can therefore be used for different purposes. Here are the differences between a UserObject and a UserFunction:

A UserObject (located in Device [image] UserObject) is an object you define that may be used just like any other object in VEE. You program a UserObject like a subprogram but it graphically remains on the screen. If you want to use it elsewhere in a program, you must clone it and maintain all copies. Note that if you clone a UserObject many times, it makes the program larger and slower to load. If you add a feature to one UserObject, you would need to add the same feature to all the other UserObjects if you want them to remain identical.

With a UserFunction (located in Device [image] UserFunction), there is just one copy of the subroutine in memory, and it is only displayed graphically in the workspace in its own window if you want it to be. Otherwise, it is stored to be called from the Call object or any other expression field. Changes to a UserFunction will be inherited by all instances in the program that call that UserFunction. You can also create libraries of UserFunctions for more code re-use.

See Also

Calling a UserFunction from an Expression, Converting Between UserObjects and UserFunctions, Creating a UserFunction Library, Importing and Calling a UserFunction, Using a Library of Functions


Overview of Compiled Functions

You can use a compiled function in a VEE program, such as a DLL (Dynamic Link Library). To do so, you must obtain the compiled function or follow these steps to create it:

1 Write functions in C, C++, Fortran, or Pascal and compile them.

2 Write a definition file for the functions.

3 Create a shared library containing the compiled functions.

Benefits of Using Compiled Functions

Using compiled functions in a VEE program offers the following benefits:

  • Faster execution speed

  • Leveraging current test programs in other languages

  • Developing data filters in other languages and integrating them into VEE programs

  • Securing proprietary routines

note

Adding compiled functions adds complexity to the development process. Therefore, use a compiled function only when the capability or performance that you need is not available with one of the following: a VEE UserFunction, an Execute Program escape to the operating system, or an ActiveX Automation call to another program.

Design Considerations in Using Compiled Functions

If you plan to use compiled functions in a VEE program, take the following information into consideration:

  • You can use any facilities available to the operating system including math routines, instrument I/O, and so forth. However, you cannot access any VEE internals from within the program to be linked.

  • You need to provide error checking within your compiled function, since VEE cannot trap errors in an external routine.

  • You must de-allocate any memory you allocated in your external routine.

  • When passing data to an external routine, make sure you configure the Call object input terminals to the type and shape of data that the routine requires.

  • System I/O resources may become locked, so your external routine should be able to handle this type of event.

  • If your external routine accepts arrays, it must have a valid pointer for the type of data it will examine. Also, the routine must check the size of the array. If the routine changes the size, you need to pass the new size back to the VEE program.

  • The compiled function must use the return() statement as its last statement, not exit(). If the compiled function exits, then so will VEE, since a compiled function is linked to VEE.

  • If you overwrite the bounds of an array, the result depends upon the language you are using. In Pascal, which performs bounds checking, a run-time error will result, stopping VEE. In languages like C, where there is no bounds checking, the result will be unpredictable, but may cause intermittent data corruption or cause VEE to crash.

Guidelines in Using Compiled Functions

When you use compiled functions in a VEE program, follow these guidelines:

  • Call and configure a Compiled Function just as you would call a UserFunction. You can either select the desired function using Select Function from the Call object menu, or you can type in the name. In either case, provided VEE recognizes the function, the input and output terminals of the Call Function object are configured automatically. The necessary information is supplied by the definition file. (VEE will recognize it if the library has already been imported.)

  • Reconfigure the Call input and output terminals by selecting Configure Pinout in the object menu. For either method, VEE configures the Call object with the input terminals required by the function, and with a Ret Value output terminal for the return value of the function. In addition, there will be an output terminal corresponding to each input that is passed by reference.

  • Call the Compiled Function by name from an expression in a Formula object or from other expressions evaluated at run time. For example, you could call a Compiled Function by including its name in an expression in a To File transaction.

note

Only the Compiled Function's return value (Ret Value in the Call object) can be obtained from within an expression. If you want to obtain other parameters returned from the function, you will have to use the Call object.

  • Delete a library of Compiled Functions by using the Delete Library object in the Device menu. Using the Import Library, Call, and Delete Library objects, you can shorten the program load time and conserve memory by importing and deleting them when the program has finished calling them.

See Also

The Definition File, Using a Compiled Function, Importing and Calling a Compiled Function, Building a C Function, Creating a Dynamic Link Library, Using Dynamic Link Libraries


The Definition File

The Call object or Formula expression determines the type of data it should pass to the function based on the contents of the definition file. The definition file defines the type of data the function returns, the function name, and the arguments the function accepts. The data has the following form:

<return type> <function name> (<type> <paramname>, <type> <paramname>, ...) ;

Where:

• <return type> can be: byte, word, int, short, long, int64, float, double, char*, VEE_BOOL, or void.

• <function name> can be a string consisting of an alpha character followed by alphanumeric characters, up to a total of 512 characters.

• <type> can be: byte, word, int, short, long, int64, float, double, VEE_BOOL, byte*, word*, int*, char*, short*, long*, int64*, float*, double*, char**, VEE_BOOL*, or void.

• <paramname> can be a string consisting of an alpha character followed by alphanumeric characters, up to a total of 512 characters. The parameter names are optional, but recommended. If a parameter is to be passed by reference, the parameter name must be preceded by the indirection symbol (*).

The valid return types are:

• character strings (char*, corresponding to the VEE Text data type)

• integers (byte, word, short, int, long, int64, VEE_BOOL, corresponding to the VEE Uint8, UInt16,Int16, Int32,Int64, and Boolean data types)

• single and double precision floating point real numbers (float and double corresponding to the VEE Real32 and Real64 data types).

If you specify "pass by reference" for a parameter by preceding the parameter name with *, VEE will pass the address of the information to your function. If you specify "pass by value" for a parameter by leaving out the *, VEE will copy the value (rather than the address of the value) to your function. You will want to pass the data by reference if your external routine changes that data for propagation back to VEE. All arrays must be passed by reference.

Any parameter passed to a Compiled Function by reference is available as an output terminal on the Call object. The output terminals will be Ret Value for the function's return value, plus an output for each input parameter that was passed by reference.

VEE pushes 144 bytes on the stack. This allows up to 36 parameters to be passed by reference to a Compiled Function. Up to 36 long integer parameters or 18 double-precision floating-point parameters may be passed by value.

VEE allows both "enclosed" comments and "to-end-of-line" comments in the definition file.

"Enclosed" comments use the delimiter sequence /*comments*/, where /* and */ mark the beginning and end of the comment, respectively.

"To-end-of-line" comments use the delimiting characters // to indicate the beginning of a comment that runs to the end of the current line.

See Also

Overview of Compiled Functions, Using a Compiled Function, Importing and Calling a Compiled Function, Building a C Function, Creating a Dynamic Link Library, Using Dynamic Link Libraries


Execute Program Object versus Compiled Functions

When you are deciding whether to use an Execute Program object or a compiled function to integrate your compiled language programs with VEE, consider the following information.

Execute Program Object

The Execute Program object has these characteristics:

  • Easier to use

  • Longer start-up time

  • Protected address space

  • Choice of synchronous or asynchronous execution

  • Service of asynchronous events

  • Safer (If the program called crashes, you get an error message.)

  • Better for continuous data acquisition

Compiled Functions

Compiled functions, using the Import Library and Call objects, have these characteristics:

  • Short start-up time

  • Communication by passing on stack and memory space shared with VEE

Synchronous execution

  • Signals and exceptions not blocked or caught (such as GPF messages)

  • Compiler for textual language required

  • More complicated to use. More risk in using. (An out-of-bounds array error or overwriting memory will cause VEE to crash.)

See Also

Overview of Compiled Functions


Remote Functions

A Remote Function is a UserFunction that runs in another VEE process on a remote host computer. Remote Functions are a special case of UserFunction.

Use

The Remote Function is called from the local VEE process over the LAN. Just as for UserFunctions and Compiled Functions, import a library of Remote Functions with the Import Library object. When one or more Remote Functions have been imported, they are called by using the Call object or by including function names in expressions. You include Remote Function calls in your program just as you would UserFunctions. However, some differences and some networking technicalities are described in this section.

Create a library of Remote Functions just as you would a library of UserFunctions, but save it on the intended remote host computer. The intended remote host computer must also have VEE Pro or VEE Pro Run Time installed on it. The library of Remote Functions is imported not into the local VEE process but in a special invocation of VEE called a "service" that runs on the remote host. The local VEE process is called the "client." The client VEE process imports the Remote Function library using the Import Library object. When you select Remote Function for the Library Type field, some new fields appear as in the following graphic.

The Library Type and Library Name fields function the same as for UserFunctions and Compiled Functions. The other fields are as follows:

Remote Host Name - The name of the host on which the "service" VEE process is to run (the "remote host"). This name can be the common or symbolic name of the host (for example myhost) or the IP address of the host in this field (for example 14.13.29.99).

Remote File Name - The name of the Remote Function library file. The Remote File Name is analogous to the File Name field for a UserFunction library. However, you must specify the absolute path to the file. Hence the path and file name can be rather long. You may want to have all users place remote function library files in a common place, such as: C:\USERS\REMFUNC.

Remote Timeout - A timeout period in seconds for communication with the VEE service. If the VEE service has not returned the expected results of a Remote Function within this time period, an error occurs.

Remote Debug - When this check box is selected, all UserFunctions within the library execute in debug mode (i.e., you will be able to perform debugging on them, such as setting breakpoints and doing line probes). This setting works with UserFunctions whether or not they have panel views.

When the Import Library object is executed (either by selecting Load Lib from the object menu or during normal program execution), a VEE server process is started on the remote host specified in the Host Name field. The client process and the server process are connected over the network and are able to communicate.

When a Call object in the client VEE calls a Remote Function, the arguments (the data input pins on the Call object) are sent over the network to the remote service, the Remote Function is executed, and the results are sent back to the Call object and output on its data output pins.

If your program deletes the library of Remote Functions with the Delete Library object, the Remote Functions associated with the library are removed. You can load multiple libraries in a VEE server process, then delete each one as needed without canceling the service connection. The VEE server exists while the VEE client process continues to run.

Prerequisite

Remote Functions requires the VEE Service Manager to be running on the remote host system. Start it manually as follows:

  1. Go to the VEE installation directory

  2. Execute veesm.exe

  3. When the console window appears, you can minimize it to get it out of the way

  4. To stop the VEE Service Manager process, open the console window and press CTRL+C.

Notes

The VEE service process executes only Remote Functions that are contained in the Remote Function library named by Import Library.

Remote Functions have views associated with them. When you call a remote function, you can have a VEE window appear on the remote host if the UserFunction displays a panel view.

Global variables (declared and undeclared) are not shared between the processes.

Remote Functions do not time-slice when called.

Parameters of type object cannot be passed to or from a Remote Function (includes ActiveX Automation objects or pointers to ActiveX controls).

The Execution Mode used by the service VEE process is that of the user’s vee.rc file, not that saved in the file that is imported.

Embedded .veeio file configurations in the file imported by the service VEE process are ignored. Only the global I/O configuration file is used.

See Also

Service Manager and UserFunction


Sequencer

An object that executes a series of sequence transactions, each of which may call a UserFunction, Compiled Function, or Remote Function.

Use

Use the Sequencer to control the order of calling of a series of UserFunctions, Compiled Functions, Remote Functions or any other VEE function by specifying a series of sequence transactions. Typically, the Sequencer is used to perform a series of tests.

The Sequencer contains a list of sequence transactions. Each of these transactions evaluates a VEE expression, which may contain a call to a UserFunction, Compiled Function, or Remote Function. After evaluating the VEE expression, a transaction compares the value returned by that expression against a test specification. Depending on whether the test passes or fails, the transaction then evaluates different expressions and selects the next transaction to be executed. Transactions may optionally log their results to the Log output pin, or to a UserFunction, Compiled Function, or Remote Function specified on the Logging categories of the Properties window.

The Return output pin of the Sequencer can be used for returning a result when the sequence has completed. By default the Return output pin has a value of zero, but a transaction with a Next Operation of Then Return will set the Return output pin to the specified value.

The Log output pin of the sequencer contains a record that contains one logging record for each transaction that has logging enabled. See "Properties" below under "Logging tab" for more information.

Open View Parameters

The open view shows the list of transactions to be executed.

Dialog Information

You can change the parameters for an individual transaction. Just double-click on a transaction to display the Sequence Transaction dialog box for that transaction. The available parameters are as follows:

Sequence Mode:

TEST - Executes the specified expression and tests the result against a specification. (If the expression calls a UserFunction, a compiled function or Remote Function, the result on the top-most output pin of the corresponding UserObject is used.)

EXEC - Executes the specified expression without performing a pass/fail test against a specification. Logging is never performed on EXEC transactions.

Transaction Name - Unique name of this transaction, and cannot be the same as any UserFunction. Must be a valid VEE variable name (must begin with a letter, but may include letters and numbers). This name can be referenced by expressions in this or other transactions, and will contain the logging record for the most recent execution of this transaction.

Enable Condition Type:

ENABLED - Sequencer unconditionally executes this transaction.

DISABLED - Sequencer never executes this transaction.

ENABLED IF: - Sequencer executes this transaction only if the given expression is non-zero.

DISABLED IF: - Sequencer does not execute this transaction if the given expression is non-zero.

SPEC NOMINAL: - Nominal (expected) value of the test result. This value is not used in calculating RANGE or LIMIT specification tests, but may be included in the logging record.

Spec Type - All specification tests are done in the same manner as the Comparator object. Thus, the test result may be a waveform, and the test limit(s) may be another waveform or an array of type Coord. The spec test will automatically perform the necessary interpolation to determine if each data point is in or out of specification. Also, all tests use an "almost equal" algorithm that checks equality or inequality to at least six significant digits. See the Comparator object description for more information. Options include:

RANGE: - Specifies a lower and upper limit and the comparison operators that apply.

LIMIT: - Specifies a single limit and the comparison operator that applies. May be used to test for an upper or lower limit, or for an exact match. The limit value will be logged in the HighLimit record field.

TOLERANCE: - Specifies a plus and minus tolerance from the Nominal value. A tolerance of zero is permitted. HighLimit and LowLimit logging record fields contain the specification range after the tolerance has been applied to the Nominal value.

%TOLERANCE: - Specifies a plus and minus percent tolerance of and from the Nominal value. A tolerance of zero is permitted. HighLimit and LowLimit logging record fields contain the specification range after the tolerance has been applied to the Nominal value.

FUNCTION - A VEE expression that specifies the test. The expression may just be a call to a UserFunction, Compiled Function, or Remote Function. Or it may be a larger expression of input pin names, UserFunctions, Compiled Functions, Remote Functions, variables, and test records from previous transactions in this Sequencer. If this is a test transaction, the single result from this field will be tested against the specification. The result of a UserFunction or Remote Function call is the value of the top-most output pin of the corresponding UserObject, or nil if no output pins are present.

Logging Mode:

LOGGING ENABLED - Add a field for this transaction to the Log record output pin (if present). If a "Log Each Transaction To:" procedure has been specified on the Logging tab in the Properties window, that logging procedure will be called immediately after this transaction is completed.

LOGGING DISABLED - A log record will not be generated for this transaction, and the "Log Each Transaction To:" procedure will not be called. (See "Logging tab" under "Properties" below for options and more information.)

Pass Operation:

IF PASS - If the spec test passes (test value within limits), the specified "then" action will be performed.

IF PASS CALL: - If the spec test passes (test value within limits), the specified VEE expression -- which may include a call to a UserFunction, Compiled Function, or Remote Function -- will be evaluated and the specified "then" action will be performed. (The return value from IF PASS CALL is ignored.)

Fail Operation:

IF FAIL - If the spec test fails (test value outside of limits), the specified "then" action will be performed.

IF FAIL CALL: - If the spec test fails (test value outside of limits), the specified VEE expression -- which may include a call to a UserFunction, Compiled Function, or Remote Function -- will be evaluated and the specified "then" action will be performed.

Next Operation: (Applies to EXEC transactions, or to either "Pass" or "Fail" operations in TEST transactions.)

THEN CONTINUE - Goes to the next transaction in the Sequencer list. (This is the default operation.)

THEN RETURN - Quits executing transactions in this Sequencer and places the value of the specified expression (which can call a function) on the Return output pin of the Sequencer. The Sequencer object will then fire its output pins and execution flow within the program will continue normally.

THEN GOTO - Goes to the transaction in this Sequencer with the specified transaction name.

THEN REPEAT - Executes this transaction again, repeating up to the specified number of times. If the Pass/Fail condition still exists after the maximum number of repeats, continues to the next transaction.

THEN ERROR - Stops execution of the Sequencer by generating an error condition with the given error number. An error can be trapped with an Error output pin on this Sequencer, or on any enclosing UserObject.

THEN EVALUATE - Evaluates the given expression -- which may call a UserFunction, Compiled Function, or Remote Function -- and uses the string result to determine the next operation. Valid string results from the expression are:

CONTINUE
RETURN <expr>
GOTO <name>
REPEAT <expr>
ERROR <expr>

Where <expr> is any valid VEE expression and <name> is the name of a transaction in this Sequencer. This operation can be useful when a UserFunction, possibly with user interaction, needs to determine what action the Sequencer should perform next.

DESCRIPTION - "Comment" field for this transaction. Text entered into this field will be shown at the end of the transaction's abbreviated text in the Sequencer open view.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Properties

LogRecordField: Selects which fields will be generated in the logging record for each transaction. (The Log output pin contains a record of records -- one logging record for each transaction with logging enabled. In each transaction logging record the selected fields, specified below, may be present.) The names (without spaces) are the field names of the logging record. The choices are:

 LogName - A unique string that identifies this transaction (not the procedure name).

 LogResult - The value returned from the evaluation of the test procedure.

 LogNominal - The nominal test value.

 LogHighLimit - The upper limit used in the specification test. Actual limit values, not offsets are given for Tolerance and %Tolerance specifications.

 LogLowLimit - Lower limit used in specification test. Actual limit values, not offsets, are given for Tolerance and %Tolerance specifications.

 LogPassed - An Int32 with value "1" for "Pass", "0" for "Fail".

 LogTimeStamp – A real value containing day, date, and time of completion of the test.

 LogDescription - A Text value containing the description "comment" field in the Transaction.

LoggingControl Category:

LogToOutputOnly - A logging record will be present in the record on the Log output pin for each transaction that has Logging Enabled. If a transaction is executed more than once during one execution of the Sequencer, only the last logging record for that transaction will be present in the record on the Log output pin. If a transaction has not been executed during an execution of the Sequencer, the logging record for that transaction will contain "0" (Real64) values for each field except the Name and Description fields, which contain null strings, and Pass which contains an Int32.

LogToFunction - Specify a UserFunction, Compiled Function, or Remote Function expression that will be called after each transaction that has Logging Enabled. To pass the logging record for the current transaction to the UserFunction, Compiled Function, or Remote Function, use the reserved variable name "ThisTest". The Log output pin will continue to operate in the same manner as for the "LogToOutputOnly" mode.

Notes

You can add an ExecTrans data input pin. The ExecTrans data input executes only the transaction(s) with the specified name(s) in the order given by a Text scalar or 1D array on the data input. The highlight bar will be moved to the transaction currently being executed. The If Pass or If Fail expressions will be evaluated as usual, but the result of the Then field will have no effect on the next transaction to be executed.

All field expressions (such as ENABLED IF, FUNCTION, or spec limits) may contain input pin names, UserFunction calls, Compiled Function calls, Remote Function calls, VEE math functions, or record names of previously run transactions. In test transactions with LOGGING ENABLED, the reserved variable, thisTest will contain a record of the logging fields that have been calculated. For example, to use the test value from transaction test4, which had logging enabled, use the name test4.result in any expression. Or to use the current test name in any expression, use thisTest.name. Or, an Enabled If expression might be random()<0.25 to cause the test to be executed only 25 percent of the time.

Note that the "thisTest" variable should not be used in the "ENABLED IF" expression because it is not created properly until the transaction determines if it is enabled or not. Therefore use of "thisTest" in the "ENABLED IF" expression will either error that thisTest is not created yet, or, thisTest might exist with "stale" data from a previous transaction.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To paste a transaction from the "kill" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

Device [image] Sequencer

See Also

Build Record, Call, Comparator, Formula, Raise Error, UnBuild Record, UserObject, Object Menu, and

To Edit a Transaction


The Sequencer Object

Sequencer Object

The Sequencer Object is in the Device menu. You should understand several topics to use the Sequencer object effectively. These topics include:

• Instrument I/O Operations (see Help [image] Contents and Index [image] Tell me about... Instrument Control Fundamentals)

• Transactions (see Help [image] Contents and Index [image] Tell me about... I/O Transactions).

• UserObjects (see Help [image] Contents and Index [image] Tell me about... Propagation [image] Propagation in UserObjects)

• Records and DataSets (see Help [image] Contents and Index [image] How Do I... Work with Data [image] Working with Records, and Working with DataSets)

• UserFunctions (see Help [image] Contents and Index [image] How Do I... Create Custom Objects and Functions [image] Creating and Using UserFunctions)

What is the Sequencer Object?

The Sequencer object controls the order of a series of tests. It does this by executing a test, then comparing the results of each test to a specification and using the comparison to determine the next action.

The Sequencer object executes a series of predetermined sequence transactions. Each transaction evaluates a VEE expression, which may contain calls to UserFunctions, Compiled Functions, Remote Functions, or other VEE functions. The transaction compares the value returned by that expression to an existing test specification. Depending on whether the test passes or fails, the transaction evaluates different expressions and selects the next transaction to be executed. You specify transaction behavior in the Sequence Transaction dialog box that appears when you click on a transaction.

Transactions may log their results to the Log output pin or to a UserFunction, Compiled Function, or Remote Function. Results can be read as they occur, collected in a Log Record, or both. Logging actions are specified in the Sequencer Properties dialog box on the Logging tab.

Logging Test Results

For some situations, you must be careful about collecting Sequencer log records into an array of records. As explained in Using Records , to build an array of records all array elements of a given field must be of the same type, shape, and size. For a record of records, as is generated by the Log output terminal of the Sequencer, the type, shape, and size of each field must match for sub-records as well.

For example, suppose you are collecting the logged results of several executions of a Sequencer, either by using the Collector to build an array or by sending the results to a DataSet. In either case, if any of the logged values of a given transaction change type, shape, or size between executions of the Sequencer, an error occurs. The error is generated by the Collector or To DataSet object because the array of records cannot be built.

This situation can easily occur if a transaction is not executed on every execution of the Sequencer, such as an ENABLED IF condition specified. If the transaction is not executed, a log record is still generated but the NAME and DESCRIPTION fields are empty strings, and all the other fields contain a Real scalar value of zero.

If the same transaction is executed on a subsequent execution of the Sequencer, and logs a result that is not a Real scalar, an error occurs. (You might want to consider, in this situation, writing each logged record out to a file in container format with To File instead of using To DataSet.)

An error can also occur if your tests return arrays of different sizes, such as an array of the failed data points. In this case, you might want to design the test to pad the array to always return the same size array.

See Also

Sequencer, Example: Bin Sort, Example: Logging Test Results, Example: Logging to a DataSet, Example: Sequencer Transactions


The Callable VEE ActiveX Automation Server

In VEE, you can integrate VEE objects into other commercial and proprietary test systems written in standard languages, such as MS Visual Basic or C. The Callable VEE ActiveX Automation Server encapsulates VEE UserFunctions and Main for integration into Automation applications, such as MS Excel and MS Visual Basic. The Callable VEE ActiveX Automation Server implements an automation interface which is language independent. It may be used by any application or language that can support calling an Automation Server.

note

VEE can use ActiveX Automation and Controls to control other applications from VEE. The Callable VEE ActiveX Automation Server allows other applications like MS Visual Basic to control VEE.

The Callable VEE ActiveX Automation Server communicates with its clients through properties and methods. The environment from which you are calling the Callable VEE ActiveX Automation Server, such as Visual Basic or C, determines how you call it. The Callable VEE ActiveX Automation Server has extensive online Help available within the environment from which you are calling it.

note

The Callable VEE ActiveX Automation Server replaces the Callable VEE ActiveX Control that was shipped with VEE version 5.0.

About Callable VEE

In some cases you may want to build an application in another language and still use VEE UserFunctions and Main. Just as Remote Functions allow one VEE to access UserFunctions or Main of another VEE, Callable VEE allows you to call UserFunctions and Main from a C program or any language that can access C routines.

Previous versions of VEE provided two ways to execute VEE code from other development environments: the VEE RPC API and the Callable VEE ActiveX Control. VEE 6 replaced the Callable VEE ActiveX Control with the Callable VEE Automation Server that allows you to easily access VEE code from programming environments like Visual Basic.

For more detailed information on Callable VEE, refer to callserv.chm at Agilent VEE install directory.

note

VEE must be accessible on the server system to run the UserFunctions. They cannot be executed on their own. UserFunctions have to be organized into a library that VEE can load and execute.

See Also

Web Monitoring with Agilent VEE, Providing Agilent VEE Data to a Remote User, Web Server Dialog Box, How a Remote User Accesses Agilent VEE on Your System, Displaying the Agilent VEE Web Server Page, Lab 13-1: Practice Session with Agilent VEE Web Browser, Restricting Access to Programs Viewed over the Web


Using the VEE RPC API

The tools needed to support the VEE RPC API are provided with VEE:

• A C library, named libvapi.lib is found in the lib subdirectory of the VEE installation. This library is to be linked to your C program.

This library supports two Application Program Interfaces (APIs). One API (VEE RPC) sets up and controls the Remote Procedure Call (RPC) between the C program and VEE. The prototypes for the functions in this API are in veeRPC.h and perform the following actions:

• Loading and unloading VEE servers.

• Loading and unloading VEE libraries.

• Listing UserFunctions in VEE libraries.

• Calling and receiving data from UserFunctions.

• Performing related status and housekeeping.

The second API (VEE DATA) performs conversions between C and VEE data types. The prototypes for the functions in this API are in veeData.h.

NOte

The libvapi.lib library cannot link to programs when using the Borland compiler.

• The VEE Service Manager, veesm.exe, is located with the other VEE executables in the VEE installation directory. It handles running the target VEE with its UserFunctions and allows a remote client to bring up VEE as a server.

There are example programs in the CallableVEE\RPC_API directory that demonstrate using the VEE RPC API. They are named callVEE.c and callVEE.exe.

About the VEE RPC API

The VEE RPC API handles setting up, maintaining, and closing the connection between the C client program and the VEE server.

The VEE RPC API's routines use one of three handles in their operation:

VRPC_SERVICE; // Handle to a VEE server.

VRPC_LIBRARY; // Handle to a VEE UserFunction library.

VRPC_FUNCTION; // Handle to a VEE UserFunction.

The API calls are organized as described in the following subsections.

See Also

Starting and Stopping a Server, Loading and Unloading a Library, Selecting UserFunctions, Calling UserFunctions, Other Functions, Error Codes for the VEE RPC API


Starting and Stopping a Server

The most essential API functions are the two that start and stop a VEE server. To load a VEE server use:

VRPC_SERVICE vrpcCreateService( char *hostName, char *display, char *geometry, double aTimeoutInSeconds,unsigned long flags );

This function starts a VEE server on the host given by hostName. The hostName can be in text form (for example, mycomputer@lvld.agilent.com) or numeric form (15.11.55.105). The function returns a server handle. You get a NULL (effectively a zero) back if something goes wrong. Thus, you can then get the precise error information with the veeGetErrorNumber() and veeGetErrorString() functions, as outlined in the next section.

The display argument specifies a remote display using a network address in text (babylon:0.0).

The geometry argument specifies VEE window size and placement. For example 800x500+0+0 puts an 800x500 VEE window in the lower-left corner of the display.

The aTimeoutInSeconds argument gives the number of seconds to wait when starting the service. This value is used for all later calls in the session unless changed by vrpcSetTimeout().

The flags argument is not normally used. However, you can set it to the value VEERPC_CREATE_NEW to start a new copy of VEE on a server instead of using the one already started.

To stop a VEE server use:

VRPC_SERVICE vrpcDeleteService( VRPC_SERVICE aService );

The only argument is the server handle obtained when you originally started the server. You get a NULL pointer back if all is OK, otherwise you get a non-NULL pointer.

See Also

Using the VEE RPC API, Loading and Unloading a Library, Selecting UserFunctions, Calling UserFunctions, Other Functions, Error Codes for the VEE RPC API


Loading and Unloading a Library

Once you have started the server, you then need to load a library into the remote copy of VEE. This is done with:

VRPC_LIBRARY vrpcLoadLibrary( VRPC_SERVICE aService, char *LibraryPath );

This function accepts as arguments a server handle and the pathname of a library of UserFunctions specified by LibraryPath and it returns a library handle. If it fails, you get a NULL back.

Once loaded, you can specify either normal or debugging execution mode for the library with:

void vrpcSetExecutionMode( VRPC_LIBRARY aLibrary, unsigned long executionMode );

In this function, you specify the handle for the library and an executionMode flag, which can be set to VRPC_DEBUG_EXECUTION (which specifies single-stepping through the UserFunction on the target system) and then set back to the default VRPC_NORMAL_EXECUTION.

You can similarly unload the library with:

VRPC_LIBRARY vrpcUnLoadLibrary( VRPC_LIBRARY aLibrary );

The only argument is the library handle.

See Also

Using the VEE RPC API, Starting and Stopping a Server, Selecting UserFunctions, Calling UserFunctions, Other Functions, Error Codes for the VEE RPC API


Selecting UserFunctions

Now that you are connected to the server and have a library loaded, you need to get a handle to a UserFunction.

You get a function handle with:

VRPC_FUNCTION vrpcFindFunction( VRPC_LIBRARY aLibrary, char *aFunctionName );

You specify the library handle and a string giving the UserFunction name as arguments and get back the function handle or a NULL if something goes wrong.

To get information on the function, use:

struct VRPC_FUNC_INFO* vrpcFunctionInfo( VRPC_FUNCTION aFunction );

This returns a data structure or a NULL if something goes wrong. The data structure is of the form:

typedef struct VRPC_FUNC_INFO

{

   char *functionName; // Name of function.

   long numArguments; // # of input pins on function.

   enum veeType *argumentTypes; // List of argument types.

   veeShape *argumentShapes; // List of argument shapes.

   long numResults; // # of output pins on function.

   enum veeType *resultTypes; // List of output types.

   veeShape *resultShapes; // List of output shapes.

};

If you get a NULL, the memory for this is taken up in your process space, so if you want to get rid of it you use:

struct VRPC_FUNC_INFO* vrpcFreeFunctionInfo(struct VRPC_FUNC_INFO *funcinfo);

You can determine what functions are in the library with:

char** vrpcGetFunctionNames( VRPC_LIBRARY aLibrary, long *numberOfFunctions );

This accepts a library handle as an argument. It returns a pointer to an array of null-terminated strings giving the function names directly and the numberOfFunctions in the library as a argument. You get a NULL pointer back if an error occurs. The string array exists in your process space.

See Also

Using the VEE RPC API, Starting and Stopping a Server, Loading and Unloading a Library, Calling UserFunctions, Other Functions, Error Codes for the VEE RPC API


Calling UserFunctions

Now you can call the UserFunction.

You call and receive in a single function using:

VDC* vrpcCallAndReceive( VRPC_FUNCTION aFunction, VDC *arguments );

This function blocks, waiting for the function to complete or until a timeout occurs. You specify a function handle and an input array of VEE Data Containers (VDCs). Handling VDCs is the function of the VEE DATA API and is covered in About the VEE DATA API.

Or, to call a UserFunction in blocking mode, you can invoke:

long vrpcCall( VRPC_FUNCTION aFunction, VDC *arguments );

This function does not "block". It returns immediately, whether it worked or not. It returns 0 if all is OK and an error code if not.

Since most UserFunctions will return sometime, you will want to get a value back and for that you use:

VDC* vrpcReceive( VRPC_FUNCTION aFunction, unsigned long waitMode );

You specify a function handle and a waitMode flag, which can have one of three values:

• VRPC_NO_WAITING The call returns immediately with or without results.

• VRPC_WAIT_SLEEPING Wait for data until timeout (server sleeps).

• VRPC_WAIT_SPINNING Wait for data until timeout (server busy).

If the function fails, a NULL is returned.

See Also

Using the VEE RPC API, Starting and Stopping a Server, Loading and Unloading a Library, Selecting UserFunctions, Other Functions, Error Codes for the VEE RPC API


Other Functions

This section lists other utility functions in the VEE RPC API:

• This function allows you to change the timeout. You specify a server handle and the timeout in seconds. You get back a zero if all is OK and an error code if not.

long vrpcSetTimeout( VRPC_SERVICE aService, double aTimeoutInSeconds );

• This function allows you to set the default C client behavior for receiving data:

long vrpcSetBehavior( VRPC_SERVICE aService, unsigned long flags );

You specify a server handle and the flag and get back 0 or an error code. The flags are as follows:

VRPC_WAIT_SLEEPING Wait for data until timeout (client sleeps).
VRPC_WAIT_SPINNING Wait for data until timeout (client busy).

You can also OR in a flag, VRPC_BUFFER_EXPAND, to specify that the C client will allocate and retain larger buffers in response to increasing sizes of data returned from the server.

• You can query the revision number of the remote veesm with:

long vrpcGetServerVersion( VRPC_SERVICE aService );

You give this a server handle and get back either a revision code or a 0 (if you have an error).

See Also

Using the VEE RPC API, Starting and Stopping a Server, Loading and Unloading a Library, Selecting UserFunctions, Calling UserFunctions, Error Codes for the VEE RPC API


Error Codes for the VEE RPC API

The following error codes are returned when a connection to the VEE server cannot be made:

Error Code | Meaning
850: eUnknownHost | The host name or IP address is unresolvable.
851: eNoServiceManager | veesm cannot be found on the server host.
861: eServiceManagerTO | The service manager timed-out.
863: eServiceNotFound | Unable to find the VEE service.
864: eServiceNotStarted | Unable to start the VEE service.
866: eConnectRefused | The connection to veesm or inetd was refused.

The following are fatal errors that occur after connection to a VEE server (the connection has been terminated):

Error Code | Meaning
852: eHostDown | The VEE server host is down.
853: eConnectTimedOut | The connection has timed out.
855: eConnectBroken | The connection has broken.

The following errors reflect an internal non-fatal state within the service:

Error Code | Meaning
865: eSomeInternalError | A non-fatal internal error occurred.
869: eVeeServiceError | There is an error within the UserFunction.
870: eWouldBlock | Returned for non-blocking RPC.
871: eDebugTermination | The user pressed stop during a debug session.

The following error is returned by a RPC function call:

Error Code | Meaning
851: eInvalidArgument | There is an invalid argument.

See Also

Using the VEE RPC API, Starting and Stopping a Server, Loading and Unloading a Library, Selecting UserFunctions, Calling UserFunctions, Other Functions


About the VEE DATA API

Performing a Call or Receive with a UserFunction requires handling data in the VEE Data Container (VDC) format, which is a set of data structures required by VEE for its internal operation. Communicating with VEE from your C program requires an ability to translate between VDCs and conventional C data types. The VEE DATA API provides this ability (and a few others).

See Also

Data Types, Shapes and Mappings, Scalar Data Handling, Array Data Handling, Enum Types, Mapping Functions, Other Functions.


Data Types, Shapes and Mappings

The fundamental VDC types are listed in the veeData.h header file as:

enum veeType

{

 VEE_TYPE_ANY=0, // The default without constraints.

   VEE_NOT_DEFINED1, // Leave space.

   VEE_LONG, // 32-bit signed integer (no 16-bit INTs in VEE).

   VEE_NOT_DEFINED2, // Leave space.

   VEE_DOUBLE, // IEEE 754 64-bit floating-point number.

   VEE_COMPLEX, // Complex number: 2 doubles in rectangular form.

   VEE_PCOMPLEX, // Complex number: 2 doubles in polar form.

   VEE_STRING, // 8-bit ASCII null-terminated string.

   VEE_NIL, // Empty container returned by function call.

   VEE_NOT_DEFINED3, // Leave space.

   VEE_COORD, // 2 or more doubles give XY or XYZ or ... data.

   VEE_ENUM, // An ordered list of strings.

   VEE_RECORD, // VEE record-structures data.

   VEE_NOT_DEFINED4, // Leave space.

   VEE_WAVEFORM, // A 1D array of VEE_DOUBLE with a time mapping.

   VEE_SPECTRUM // A 1D array of VEE_PCOMPLEX with a time mapping.

   VEE_LONGLONG, // 64-bit signed integer.

   VEE_BOOLEAN // 32-bit signed integer.

   VEE_WORD // 16-bit unsigned integer.

};

For convenience, the veeData.h file defines C data types for translation with VEE data types:

typedef short int16;

typedef long int32;

typedef __int64 int64;

typedef long VEE_BOOL;

typedef unsigned short u_int16;

typedef struct {double rval, ival;} veeComplex;

typedef struct {double mag, phase;} veePComplex;

typedef struct {double xval, yval;} vee2DCoord;

typedef struct {double xval, yval, zval;} vee3DCoord;

typedef void veeDataContainer;

typedef veeDataContainer* VDC;

The data types can also have a specified number of dimensions, or numDims, given by:

enum veeShape

{

   VEE_SHAPE_SCALAR, // A single data element.

   VEE_SHAPE_ARRAY1D, // A one-dimensional array.

   VEE_SHAPE_ARRAY2D, // A two-dimensional array.

   VEE_SHAPE_ARRAY3D, // A three-dimensional array.

   VEE_SHAPE_ARRAY, // An array with from 4 to 10 dimensions.

   VEE_SHAPE_ANY // Placeholder for undefined shape.

};

Arrays can be "mapped". Normally they are not, but the VEE_WAVEFORM and VEE_SPECTRUM data types are mapped types where the array elements correspond to time intervals. Mappings are given by:

enum veeMapType

{

   VEE_MAPPING_NONE, // No mapping.

   VEE_MAPPING_LINEAR, // Linear mapping.

   VEE_MAPPING_LOG // Log mapping.

};

Generally, you do not need specify mappings.

See Also

About the VEE DATA API, Scalar Data Handling, Array Data Handling, Enum Types, Mapping Functions, Other Functions.


Scalar Data Handling

To create VDC scalars from C data, use the following functions:

VDC vdcCreateWordScalar(u_int16 aWord);

VDC vdcCreateBooleanScalar(VEE_BOOL aBool);

VDC vdcCreateLongScalar( int32 aLong );

VDC vdcCreateLongLongScalar(int64 aLong);

VDC vdcCreateDoubleScalar( double aReal );

VDC vdcCreateStringScalar( char *aString );

VDC vdcCreateComplexScalar( double realPart, double imaginaryPart );

VDC vdcCreatePComplexScalar( double magnitude, double phase );

VDC vdcCreate2DCoordScalar( double xval, double yval );

VDC vdcCreate3DCoordScalar( double xval, double yval, double zval );

VDC vdcCreateCoordScalar( int16 aFieldCount, double *values );

All these functions return a pointer to a VDC, or a NULL if they fail. There are no scalars of VEE_WAVEFORM or VEE_SPECTRUM types as they are always 1D arrays by definition.

You can change the values in the VDCs with another set of routines:

int32 vdcSetWordScalar(VDC aVD, u_int16 aWord);

int32 vdcSetBoolScalar(VDC aVD, VEE_BOOL aBool);

int32 vdcSetLongScalar( VDC aVD, int32 aLong );

int32 vdcSetLongLongScalar(VDC aVD, int64 aLongLong);

int32 vdcSetDoubleScalar( VDC aVD, double aReal );

int32 vdcSetStringScalar( VDC aVD, char *aStr );

int32 vdcSetComplexScalar( VDC aVD, double realPart, double imaginaryPart );

int32 vdcSetPComplexScalar( VDC aVD, double magnitude, double phase );

int32 vdcSet2DCoordScalar( VDC aVD, double xval, double yval );

int32 vdcSet3DCoordScalar( VDC aVD, double xval, double yval, double zval );

int32 vdcSetCoordScalar( VDC aVD, int16 aFieldCount, double* values );

As described above, these functions return either 0 or an error code.

When you have created a scalar VDC or returned one from a function, you can get the C data type out of it with another set of routines:

int32 vdcGetWordScalarValue(VDC aVD, u_int16 *aWord);

int32 vdcSetBoolScalar(VDC aVD, VEE_BOOL aBool);

int32 vdcGetLongScalarValue( VDC aVD, int32 *aLong );

int32 vdcSetLongLongScalar(VDC aVD, int64 aLongLong);

int32 vdcGetDoubleScalarValue( VDC aVD, double *aReal );

char* vdcGetStringScalarValue( VDC aVD );

int32 vdcGetComplexScalarValue( VDC aVD, veeComplex *aComplex );

int32 vdcGetPComplexScalarValue( VDC aVD, veePComplex *aPComplex );

int32 vdcGet2DCoordScalarValue( VDC aVD, vee2DCoord *aCoord );

int32 vdcGet3DCoordScalarValue( VDC aVD, vee3DCoord *aCoord );

double* vdcGetCoordScalarValue( VDC aVD, int16 *aFieldCount );

In general, these functions take the data out of the first argument, a VDC, and put it into the second, which is a C variable (with some types as defined at the beginning of this section). They return 0 if no error and an error code if there is an error.

The exceptions are the vdcGetStringScalarValue() function, which returns a string directly from the function (or a NULL string if something goes wrong) and the vdcGetCoordScalarValue() function, which returns a pointer to an array of N-dimensional coordinate data (with N returned as an argument).

Finally, you can interrogate coordinate types for their number of coordinate dimensions or set the coordinate dimensions to new values if desired:

int16 vdcNumCoordDims( VDC aVD );

int32 vdcCoordSetNumCoordDims( VDC, int16 );

See Also

About the VEE DATA API, Data Types, Shapes and Mappings, Array Data Handling, Enum Types, Mapping Functions, Other Functions.


Array Data Handling

These functions create array VDC of VEE types. The values you supply are copied into the VDC. The caller’s memory is never used. If an error occurs a null pointer is returned. You create VDC arrays with the following set of functions:

• This function returns a VDC of type VEE_BOOL which is allocated to a size equal to the argument, numPts. The array of data pointed to by the argument, values, must be of the same specified size. The type of the argument, VEE_BOOL, is type defined to type long in veeData.h.

VDC vdcCreateBoolean1DArray(int32 numpts, VEE_BOOL *values);

• This function returns a VDC of type VEE_LONG which is allocated to a size equal to the argument, numPts. The array of data pointed to by the argument, values, must be of the same specified size. The type of the argument, int32, is type defined to type long in veeData.h.

VDC vdcCreateLong1DArray( int32 numPts, int32 *values );

• This function returns a VDC of type VEE_LONGLONG which is allocated to a size equal to the argument, numPts. The array of data pointed to by the argument, values, must be of the same specified size. The type of the argument, int64, is type defined to type __int64 in veeData.h.

VDC vdcCreateLongLong1DArray(int32 numpts, int64 *values);

• This function returns a VDC of type VEE_STRING which is allocated to a size equal to the argument, numPts. The argument, strings, points to an array of pointers which in turn point to null terminated strings. The number of strings in the array must equal the specified size. The type of the argument, int32, is type defined to type long in veeData.h.

VDC vdcCreateString1DArray( int32 numPts, char **strings );

• This function returns a VDC of type VEE_DOUBLE which is allocated to a size equal to the argument, numPts. The argument, values, points to an array of data. The number of doubles in the array must equal the specified size. The type of the argument, int32, is type defined to type long in veeData.h.

VDC vdcCreateDouble1DArray( int32 numPts, double *values );

• This function returns a VDC of type VEE_COMPLEX which is preallocated to a size equal to the argument, numPts. The type of the argument, int32, is type defined to type long in veeData.h. The argument, values, points to an array of structures of type veeComplex. This structure is defined in veeData.h as:

typedef struct {double rval, ival;} veeComplex;

VDC vdcCreateComplex1DArray( int32 numPts, veeComplex *values );

• This function returns a VDC of type VEE_PCOMPLEX which is preallocated to a size equal to the argument, numPts. The type of the argument, int32, is type defined to type long in veeData.h. The argument, values, points to an array of structures of type veePComplex. This structure is defined in veeData.h as:

typedef struct {double mag, phase;} veePComplex;

VDC vdcCreatePComplex1DArray( int32 numPts, veePComplex *values );

• This function returns a VDC of type VEE_COORD which is preallocated to a size equal to the argument, numPts. The type of the argument, int32, is type defined to type long in veeData.h. The argument, values, points to an array of structures of type vee2DCoord. This structure is defined in veeData.h as:

typedef struct {double xval, yval;} vee2DCoord;

VDC vdcCreate2DCoord1DArray( int32 numPts, vee2DCoord *values );

• This function returns a VDC of type VEE_COORD which is preallocated to a size equal to the argument, numPts. The type of the argument, int32, is type defined to type long in veeData.h. The argument, values, points to an array of structures of type vee3DCoord. This structure is defined in veeData.h as:

typedef struct {double xval, yval, zval;} vee3DCoord;

VDC vdcCreate3DCoord1DArray( int32 numPts, vee3DCoord *values );

• This function returns a VDC of type VEE_COORD which is preallocated to a size equal to the argument, numPts. The argument, aFieldCount, is the number of fields in the coordinates. The type of the argument, int32, is type defined to type long in veeData.h. The argument, values, points to an array of type double. The length of this array must be equal to the product of numPts and aFieldCount.

VDC vdcCreateCoord1DArray( int32 numPts, int16 aFieldCount, double *values );

• This function returns a VDC of type VEE_WAVEFORM with a number of samples equal to the argument, numPts. The starting and ending times for the waveform are the arguments, from and thru. The argument, mapType, is of type VMT, defined in veeData.h since it declares what type of mapping is used. See Data Types, Shapes and Mappings for more information.

The array of doubles pointed to by the argument, data, must be equal in size to the argument, numPts. The type of the argument, int32, is type defined to type long in veeData.h.

VDC vdcCreateWaveform( int32 numPts, double from, double thru, VMT mapType, double *data );

• This function returns a VDC of type VEE_SPECTRUM with a number of samples equal to the argument, numPts. The starting and ending frequencies for the spectrum are the arguments, from and thru. The argument, mapType, is of type VMT, defined in veeData.h since it declares what type of mapping is used. See Data Types, Shapes and Mappings” for more information.

The array of type veePComplex pointed to by the argument, data, must be equal in size to the argument, numPts.Type. veePComplex is a structure defined in veeData.h:

typedef struct {double mag, phase;} veePComplex.

The array of structures is copied. The type of the argument, int32, is type defined to type long in veeData.h.

VDC vdcCreateSpectrum( int32 numPts, double from, double thru,
VMT mapType, veePComplex *data);

In the functions listed above, you specify an array size, any additional data needed to represent the array (such as mapping data for VEE_WAVEFORM and VEE_SPECTRUM types) and the array data and get back a VDC (or a NULL if something goes wrong).

You can convert back from VDCs to C arrays with:

• This function returns a pointer to an array of type VEE_BOOL. The argument, aVD, must be of type, VEE_BOOL and be an array. The value returned in the pass-by-reference argument, numPts, is the length of the array.

VEE_BOOL* vdcGetBool1DArray(VDC aVD, int32 *numpts);

• This function returns a pointer to an array of type int32. The argument, aVD, must be of type, VEE_LONG and be an array. The value returned in the pass-by-reference argument, numPts, is the length of the array.

int32* vdcGetLong1DArray( VDC aVD, int32 *numPts );

• This function returns a pointer to an array of type int64. The argument, aVD, must be of type, VEE_LONGLONG and be an array. The value returned in the pass-by-reference argument, numPts, is the length of the array.

int64* vdcGetLongLong1DArray(VDC aVD, int32 *numpts);

• This function returns a pointer to an array of type double. The argument, aVD, must be of type, VEE_DOUBLE. The value returned in the pass-by-reference argument, numPts, is the length of the array.

double* vdcGetDouble1DArray( VDC aVD, int32 *numPts );

• This function returns a pointer to an array of pointers each pointing to a null terminated string. The argument, aVD, must be of type VEE_STRING. The value returned in the pass-by-reference argument, numPts, is the number of strings.

char** vdcGetString1DArray( VDC aVD, int32 *numPts );

• This function returns a pointer to an array of structures of type, veeComplex. This structure is defined in veeData.h as:

typedef struct {double rval, ival;} veeComplex;

The argument, aVD, must be of type VEE_COMPLEX. The value returned in the pass-by-reference argument, numPts, is the length of the array.

veeComplex* vdcGetComplex1DArray( VDC aVD,int32 *numPts );

• This function returns a pointer to an array of structures of type, veePComplex. This structure is defined in veeData.h as:

typedef struct {double mag, phase;} veePComplex;

The argument, aVD, must be of type VEE_PCOMPLEX. The value returned in the pass-by-reference argument, numPts, is the length of the array.

veePComplex* vdcGetPComplex1DArray( VDC aVD, int32 *numPts );

• This function returns a pointer to an array of structures of type, vee2DCoord. This structure is defined in veeData.h as:

typedef struct {double xval, yval;} vee2DCoord;

The argument, aVD, must be of type VEE_COORD. The value returned in the pass-by-reference argument, numPts, is the length of the array.

vee2DCoord* vdcGet2DCoord1DArray( VDC aVD, int32 *numPts );

• This function returns a pointer to an array of structures of type, vee3DCoord. This structure is defined in veeData.h as:

typedef struct {double xval, yval, zval;} vee3DCoord;

The argument, aVD, must be of type VEE_COORD. The value returned in the pass-by-reference argument, numPts, is the length of the array.

vee3DCoord* vdcGet3DCoord1DArray( VDC aVD, int32 *numPts );

• This function returns a pointer to an array of type double. The argument, aVD, must be of type VEE_COORD. The value returned in the pass-by-reference argument, numPts, is the number of coordinate tuples in the array. The value returned in the pass-by-reference argument, aFieldCount, is the number of fields in each coordinate tuple. The length of the returned array is the product of numPts and aFieldCount.

double* vdcGetCoord1DArray( VDC aVD, int32 *numPts, int16 *aFieldCount );

• This function returns a pointer to an array of type double. The argument, aVD, must be of type VEE_WAVEFORM. The pass-by-reference arguments numPts, from, thru and mapType return, respectively, the length of the array, the start time, the end time and the type of mapping.

double* vdcGetWaveform( VDC aVD, int32 *numPts, double *from, double *thru, VMT *mapType );

• This function returns a pointer to an array of structures of type veePComplex. This structure is defined in veeData.h as:

typedef struct {double mag, phase;} veePComplex;

The argument, aVD, must be of type VEE_WAVEFORM. The pass-by-reference arguments numPts, from, thru and mapType return, respectively, the length of the array of structures, the starting frequency, the ending frequency, and the type of mapping.

veePComplex* vdcGetSpectrum( VDC aVD, int32 *numPts, double *from, double *thru, VMT *mapType );

These functions take a VDC, return a pointer to the array of data directly and return the size of the array (or any other relevant information) as arguments.

Once the arrays are created, you can also check, interrogate, or manipulate the arrays with the following functions:

int32 vdcSetNumDims( VDC, int16 );

int16 vdcGetNumDims( VDC );

int32 vdcSetDimSizes( VDC, int32* );

int32 *vdcGetDimSizes( VDC );

int32 vdcCurNumElements( VDC );

See Also

About the VEE DATA API, Data Types, Shapes and Mappings, Scalar Data Handling, Enum Types, Mapping Functions, Other Functions.


Enum Types

VEE enumerated types, as noted, are ordered lists of strings and are handled by the following routines:

• This function creates an empty VEE_ENUM structure with the given number of string-ordinal pairs. It returns a NULL VDC on error.

VDC vdcCreateEnumScalar( int16 numberOfPairs );

• This function places an enumerated pair in the defined VEE ENUM structure, returns the updated structure and returns 0 or an error code.

int32 vdcEnumAddEnumPair( VDC aVD, char* aString, int32 aValue );

• This function deletes an enumerated pair as given by the ordinal value argument. It returns 0 or an error code.

int32 vdcEnumDeleteEnumPairWithOrdinal( VDC aVD, int32 anOrd );

• This function sets an ordinal value for use by other vdcEnum routines. It returns 0 or an error code.

int32 vdcSetEnumScalar( VDC aVD, int32 anOrdinal );

This function places a string in the VEE_ENUM structure with the ordinal value assigned by vdcSetEnumScalar().

int32 vdcEnumDeleteEnumPairWithStr(VDC aVD, char* aString );

This function returns the current ordinal number selection assigned by vdcSetEnumScalar().

int32 vdcGetEnumOrdinal( VDC aVD );

• This function returns the string associated with the current ordinal number, or a NULL string if something goes wrong.

char* vdcGetEnumString( VDC aVD );

See Also

About the VEE DATA API, Data Types, Shapes and Mappings, Scalar Data Handling, Array Data Handling, Mapping Functions, Other Functions.


Mapping Functions

The VEE DATA API allows you to manipulate the mappings of arrays with the following functions:

int32 vdcAtDimPutLowerLimit( VDC aVD, int16 aDim, double aValue );

// Specify mapping for lower limit.

int32 vdcAtDimPutUpperLimit( VDC aVD, int16 aDim, double aValue );

// Specify mapping for upper limit.

int32 vdcAtDimPutRange( VDC aVD, int16 aDim, double lowerLimit, double upperLimit );

// Combines "vdcAtDimPutLowerLimit" &
// "vdcAtDimPutUpperLimit".

int32 vdcAtDimPutMapping( VDC aVD, int16 aDim, VMT aMapping);

// Set the mapping between limits as defined above.

int32 vdcMakeMappingsSame( VDC VD1, VDC VD2 );

// Map two containers in the same way.

int32 vdcUnMap( VDC aVD );

// Delete mapping information from container.

See Also

About the VEE DATA API, Data Types, Shapes and Mappings, Scalar Data Handling, Array Data Handling, Enum Types, Other Functions.


Other Functions

Other VEE DATA API functions include:

• Get the type of VDC. Return VEE_NOTDEFINED1 on error.

enum veeType vdcType( VDC aVD );

• Make a copy of a VDC. Return NULL on error.

VDC vdcCopy( VDC oldVD );

• Destroy a container and release its memory. Return NULL on error.

VDC vdcFree( VDC aVD );

• Get error number/message of last error.

int16 veeGetErrorNumber( void );

char *veeGetErrorString( void );

• Reset error number to zero.

void veeClearErrorNumber(void)

The libvapi.lib library cannot link to programs when using the Borland compiler.

See Also

About the VEE DATA API, Data Types, Shapes and Mappings, Scalar Data Handling, Array Data Handling, Enum Types, Mapping Functions.


Overview of Web Technologies

You can use VEE to disseminate data you have collected in programs, to monitor test systems, or to review test results remotely.

This example describes how to create a web site internal to an organization (an intranet web site) that provides reference data as a server. It assumes that users accessing this site have browsers. The example uses a Microsoft environment (Windows Vista, Windows 2000, or Windows XP), MS Office, and MS Internet Explorer. The communication goes from the instrument to the server, and then to the client browser.

note

This example uses PC screen dumps.

In above figure, the communication is as follows:

• The device under test (DUT), or sensor, or instrument sends information to the server application through the network I/O layer. The network I/O layer includes the interface and backplane (GPIB, RS232, VXI, MXI, USB, LAN, PC Plug-in), and the I/O programming layer such as drivers, VISA, or SICL.

• The server application is the VEE program that generates the measurement data.

• The HTTP (HyperText Transfer Protocol) sends the information to the client browser.

HTTP is one protocol in the TCP/IP communications protocol used by the Web. (TCP/IP stands for Transmission Control Protocol/Internet Protocol.) Lower levels of the TCP/IP protocols include transport, network, and physical layers of communication. By definition, every TCP/IP application is a client/server application. For example, the Client Browser, such as Internet Explorer, can request information generated by the server application.

When the Universal Resource Locator (URL) below is typed into Internet Explorer, it requests information from an Agilent server:

http://www.agilent.com/find/vee

• http describes the type of resource being accessed to transfer the information.

• www.agilent.com/find/vee is the URL for the resource. The hypertext format used by HTTP is a scripting format called HyperText Markup Language (HTML). HTML is a way to link documents together, and originally it was the only language programmers could use to create Web pages. Originally just for text, HTML now incorporates sound, video, images, interactive screens, ActiveX controls and Java applets.

Once a request is made by the browser for the server information, it will not automatically update, unless the browser is designed to do so. Also, no interaction is allowed by the browser unless it is designed into the browser page. The easiest way to do this is with a scripting language, such as VBScript, JavaScript, and Jscript.

The scripting language is an interpreted language supported by the browser. The scripting language can extend the limitations of HTML to provide a more interactive Web page. Because they are interpreted, scripting languages must be embedded into the Web page and supported by the browser. They are not independent programs. This is graphically illustrated here.

VBScript, JavaScript, and JScript are scripting languages. VBScript is based on MS Visual Basic. JavaScript is co-created by Sun (Java). JScript is based on Microsoft’s version of JavaScript.

The scripting languages must reside inside a host application. The host application is typically a web browser such as Internet Explorer or Netscape Navigator. Within the browser, the overall look and feel of the web page is controlled by HTML.

Microsoft’s Component Object Model (COM) defines compiled software components called ActiveX Controls that encapsulate specifically designed functions. Typically, an ActiveX Control is used to provide user interface functionality and is designed to run on the client computer. ActiveX Controls are optimized software components that used to be called OLE Controls.

See Also

The Callable VEE ActiveX Automation Server, Web Monitoring with Agilent VEE, Providing Agilent VEE Data to a Remote User, Web Server Dialog Box, How a Remote User Accesses Agilent VEE on Your System, Displaying the Agilent VEE Web Server Page, Lab 13-1: Practice Session with Agilent VEE Web Browser, Restricting Access to Programs Viewed over the Web


Web Monitoring with Agilent VEE

VEE includes a built-in Web server that can communicate with other programs via HTTP. You can allow remote users to access VEE programs and information that resides on your computer. This section describes how you would share VEE data, and how a remote user would access the data.

General Guidelines and Tips

• The VEE program running on your system is the VEE program that the remote user will access.

• Your system must be running VEE. The remote user does not need to have VEE installed in order to access a VEE program on your system.

• When the remote user sends a request from their network browser to VEE, VEE creates a picture to display in the remote user’s browser window. This picture is a “snapshot” of the VEE program. (It cannot be edited.)

• By making choices in the VEE Web Server Home Page or by specifying command line options in the browser URL, a remote user can view different parts of your VEE program, have the VEE program refresh the browser display at regular intervals (to monitor the program’s progress), and display error message information.

See Also

The Callable VEE ActiveX Automation Server, Providing Agilent VEE Data to a Remote User, Web Server Dialog Box, How a Remote User Accesses Agilent VEE on Your System, Displaying the Agilent VEE Web Server Page, Lab 13-1: Practice Session with Agilent VEE Web Browser, Restricting Access to Programs Viewed over the Web


Providing Agilent VEE Data to a Remote User

To set up the VEE Web server so that a remote user can access data on your system, follow these general steps:

1 Make sure your system is connected to a network.

2 Provide information to the remote user about the URL he or she will enter in the browser to access your system (which is described in more detail later).

3 Start VEE, and open the program that you want the remote user to access, and/or create any files you want the remote user to access.

4 Enable the Web Server by selecting the File [image] Default Preferences [image] Web Server dialog box settings which are described in more detail below.

5 Have the remote user run a Web browser such as Internet Explorer or Netscape.

See Also

The Callable VEE ActiveX Automation Server, Web Monitoring with Agilent VEE, Web Server Dialog Box, How a Remote User Accesses Agilent VEE on Your System, Displaying the Agilent VEE Web Server Page, Lab 13-1: Practice Session with Agilent VEE Web Browser, Restricting Access to Programs Viewed over the Web


Web Server Dialog Box

When you select File [image] Default Preferences [image] Web Server, the Web Server dialog box appears as follows.

The fields in the Web Server dialog box are as follows:

Field Name

Description

Enable Server

When checked, Enable Server turns on VEE’s built-in Web server. The Web server allows a remote user to view, monitor and troubleshoot VEE programs on your system, by using a Web browser to display your VEE program.

VEE’s Web server uses the standard HTTP protocol. By default, Enable Server is OFF (not checked). Your system must be connected to a network, VEE must be running, and the remote user must have a Web browser running for the remote user to access the VEE Web server.

Root Directory

Specifies the location of files that are accessible to a remote user. The default is ~installDir/www. For Windows Vista, Windows XP, or Windows2000, if VEE Pro8.5 is installed with the defaults, this field will read:

C:\Program Files\Agilent\VEE Pro 8.5\www.

• Do not put private files in this directory or any of its subdirectories, since they can be viewed by any remote user with a Web browser that has access to your system.

• VEE installs the file index.html in the default Web server Root Directory when you install VEE. By default, the file will be in C:\Program Files\Agilent\VEE Pro 8.0\www\index.html. This is the default VEE Web server home page, which can be displayed when a remote user accesses your system. (You can edit the home page for your needs, if you like.)

• If you change the root directory for Web files, move the index.html file to the new directory and do not change its name.

HTTP Port Number

Specifies the port number for the VEE Web server. The default port number is 80. The only time you need to change the default port number is when another Web server, such as another instance of VEE, is running on the same system, or if you want to restrict the remote user access to your VEE Web server.

• By specifying an HTTP port between 0 and 65535, you can restrict who can access and view data on your system.

• If you enter a different port number, the remote user that views the VEE program must enter the same port number in his or her browser. For example, if you set this field to port 85, the remote user would type in the URL as http://hostname:85. (There is more information about the definition of hostname later in this chapter.)

Server Timeout

Specifies the maximum time that the VEE Web server will wait for VEE to process commands. By default, this field is set to 60 seconds. If the VEE program takes longer than the specified time to process a command, VEE sends a timeout to the Web server.

Log File

Specifies the log file where all incoming HTTP requests, processed by the Web server, are recorded. The default location for this file on a PC is C:\windows\TEMP\http.log. If the log file does not already exist, it is created when you make changes in the Default Preferences [image] Web Server dialog.

Save

The values will be the default for future VEE Web sessions until you change them again. To use the specified values only for the current VEE session, click OK.

See Also

The Callable VEE ActiveX Automation Server, Web Monitoring with Agilent VEE, Providing Agilent VEE Data to a Remote User, How a Remote User Accesses Agilent VEE on Your System, Displaying the Agilent VEE Web Server Page, Lab 13-1: Practice Session with Agilent VEE Web Browser, Restricting Access to Programs Viewed over the Web


How a Remote User Accesses Agilent VEE on Your System

To access VEE files on your system from another location, the remote user needs to follow these general steps:

1 The remote user’s system must be connected to a network.

2 The remote user must be running a network browser, such as Netscape or Internet Explorer.

3 The remote user must enter a URL address for your system. (You provide the address to the remote user, which is explained in more detail below.)

note

The remote user does not have to be running VEE or even have VEE installed in order to access VEE programs on your system.

The remote user connects to the network and runs the browser, and enters a URL. You will tell the remote user the URL to enter based on the following information. The formats you can have the remote user enter are as follows:

http://hostname {:port}

Displays your VEE Web Server Home Page, where the remote user can enter choices about how to view your VEE program.

http://hostname{:port}{/command}{?parameter}

Specifies a view or UserFunction for the remote user to view in the VEE program. For example, http://hostname/ViewMainDetail displays the Detail view of your main VEE program.

http://hostname{:port}{/file}

Specifies a file that you have saved, such as a *.jpeg or *.html file, that you want the remote user to view.

note

The fields in wavy parentheses {} are optional fields.

The fields in the URL addresses are as follows:

The commands and parameters that can be used in URLs when a remote user accesses a VEE program on your system are as follows.

Field Name

Description

Hostname

(Required) Identifies your system, where VEE is running, in the format <computer_name>.domain.com.

You may choose to have a remote user type in only the <hostname> in a URL, such as http://<hostname>. This command opens your VEE Web Server Home Page index.html and displays it to the remote user. The remote user can make choices from your VEE Web Server Home Page menu to display, monitor, or troubleshoot your VEE program.

Port

(Optional) Identifies the Web Server port number if not using the default value 80. Specify this value only when the port number you entered in File [image] Default Preferences [image] Web Server is a number other than 80.

For example, if the remote user is accessing VEE on your system, and the port number in yourFile [image] Default Preferences [image] Web Serveris set to 85, you would have the remote user enter http://<hostname>:85.

File

(Optional) Identifies a directory and/or file relative to the root directory for the browser to open. You would only specify a file when you have saved a file such as a *.jpeg or *.html for a remote user to view.

In order for remote users to display a file from your system, you must specify the directory as the Root Directory in the Web Server dialog in Default Preferences in VEE.

Commands and Parameters

(Optional) Specifies a command or a parameter required for a command that is supported by the VEE Web Server. Commands and parameters enable a remote user to monitor and troubleshoot a remote VEE program through the browser. The following lists the commands and parameters.

Viewing the entire VEE window

ViewVEE

For example, http://hostname/ViewVEE

Panel view of main VEE program

ViewMainPanel

For example,

http://hostname/ViewMainPanel

Detail view of main VEE program

ViewMainDetail

For example,

http://hostname/ViewMainDetail

VEE execution window during runtime

ViewExecWindow

For example

http://hostname/ViewExecWindow

VEE UserFunction in Panel view

http://hostname/ViewPanel?

<UserFunction Name>

For example, if the UserFunction is AddNoise, the remote user would enter

http://hostname/ViewPanel? AddNoise

Detail view of a UserFunction

http://hostname/ViewDetail?

UserFunctionName

For example, if the UserFunction is AddNoise the remote user would enter

http://hostname/ViewPanel? AddNoise

Error window of current program

http://hostname/ViewError

Display list of available command URLs.

ViewHelp

See Also

The Callable VEE ActiveX Automation Server, Web Monitoring with Agilent VEE, Providing Agilent VEE Data to a Remote User, Web Server Dialog Box, Displaying the Agilent VEE Web Server Page, Lab 13-1: Practice Session with Agilent VEE Web Browser, Restricting Access to Programs Viewed over the Web


Displaying the Agilent VEE Web Server Page

When you install VEE, it creates a default index.html file in the www directory. This file contains the VEE Web Server Home Page. You can have remote users click choices on this page for displaying your VEE program. The default VEE Web Server Home Page is shown here. You can also edit the page, in MS Word, for example, to suit your needs.

note

To display this menu on your own system, you can refer to your system as localhost. For example, if you run VEE, run the network browser, and enter http://localhost, the browser will display the VEE Web Server Home Page shown above. This is an easy way for you to check what the remote user will display with different commands.

When the remote user displays the menu shown above, he or she can access various parts of a VEE program by making choices in the menu. For example, the user can click on Main Detail to view the Main VEE program in Detail view. Making the choice in the menu displays the same information as having the remote user enter the command http://hostname/ViewMainDetail in the network browser.

See Also

The Callable VEE ActiveX Automation Server, Web Monitoring with Agilent VEE, Providing Agilent VEE Data to a Remote User, Web Server Dialog Box, How a Remote User Accesses Agilent VEE on Your System, Lab 13-1: Practice Session with Agilent VEE Web Browser, Restricting Access to Programs Viewed over the Web


Restricting Access to Programs Viewed over the Web

When you make a VEE program available on the Web, you may still want to restrict remote users from seeing certain parts of it. If remote users currently know the URL to your system, you want to make sure that only certain remote users are able to access particular programs or Web directory files.

To prevent remote users from viewing parts of a VEE program on the Web, you can protect the program in three different ways:

Change the port number in the Default Preferences [image] Web Server folder so only authorized users may view the program.

-OR-

Create a secured RunTime version of the VEE program. This will ensure that none of the program code can be viewed. For more information, refer to Create RunTime Version

-OR-

Create an HTML file with the exact name of the command you want to disable, and save it in the VEE www directory. The browser always accesses any *.html file before going to VEE. In this way, you can intercept requests from remote users and display an HTML page with the appropriate warning or comments.

For example, you might want to prevent remote users from seeing the Detail view of a VEE program. You could create a file in a program such as MS Word and save it as ViewMainDetail.html in the www directory. In the file, you put the message you want the remote user to see.

When the remote user chooses Main Detail in the VEE Web Server Home Page or enters a URL with the option ViewMainDetail, the browser does not display the main VEE program in detail view. Instead, the browser accesses the ViewMainDetail.html file in the www directory and displays the file you created. Here is an example of what you could display to a remote user.

note

Make sure the file name is the file name of a VEE web command, and that it is located in the Root Directory specified in Web Server.

You could also use an *.html file for other purposes, such as putting password protection on a VEE program so that only users with the password can view the program. Here is an example of password protection.

See Also

The Callable VEE ActiveX Automation Server, Web Monitoring with Agilent VEE, Providing Agilent VEE Data to a Remote User, Web Server Dialog Box, How a Remote User Accesses Agilent VEE on Your System, Displaying the Agilent VEE Web Server Page, Lab 13-1: Practice Session with Agilent VEE Web Browser


MATLAB Script Overview

MATLAB® Script is a subset of the standard, full-featured MATLAB from The MathWorks. It gives users direct access to the core set of MATLAB functionality, such as advanced mathematics, data analysis, and scientific and engineering graphics. The MATLAB Script object can be easily included in any Agilent VEE program.

MATLAB Script includes hundreds of functions for:

• Data analysis and visualization

• Numeric computation, including:

• Linear algebra and matrix computation

• Fourier and statistical analysis

• Differential equation solving

• Trigonometric and fundamental math operations

• Engineering and scientific graphics, such as:

• 2-D and 3-D display, including triangulated and gridded data

• Volume visualization of scalar and vector data

• Quiver, ribbon, scatter, bar, pie, and stem plots

Signal Processing Toolbox

MATLAB Script for VEE also includes a subset of the MATLAB Signal Processing Toolbox, which is built on a solid foundation of filter design and spectral analysis techniques. Functions are included for:

• Signal and linear system models

• Analog filter design

• FIR and IIR digital filter design, analysis, and implementation

• Transforms such as FFT and DCT

• Spectrum estimation and statistical signal processing

• Parametric time-series modeling

• Waveform generation

About Full-Featured MATLAB

MATLAB is an integrated technical computing environment that combines numeric computation, advanced graphics and visualization, and a high-level programming language. MATLAB includes hundreds of functions for:

• Data analysis and visualization

• Numeric and symbolic computation

• Engineering and scientific graphics

• Modeling, simulation, and prototyping

• Programming, application development, and GUI design

MATLAB is used in a variety of application areas including signal and image processing, control system design, financial engineering, and medical research. The open architecture makes it easy to use MATLAB and companion products to explore data and create custom tools that provide early insights and competitive advantages.

As a VEE user, you can incorporate the full power of MATLAB and the Signal Processing Toolbox for applications involving data analysis, visualization and modeling. By upgrading to the full versions of these products, you can use a wide range of additional MATLAB features in VEE applications, such as creating user-defined functions (M-files), and access to the MATLAB command window, the MATLAB Editor/Debugger, and the Signal Processing GUI.

To use the full-featured MATLAB you have installed in VEE, refer to Choose a MATLAB to use in VEE.

Sources of Additional Information for MATLAB

For complete, detailed information on using the MATLAB Script object, refer to the MATLAB Script Help Desk. In VEE, select Help [image] MATLAB Script [image] Help Desk. The MATLAB Help Desk will appear in a Web browser.

For further information about MATLAB, MATLAB Toolboxes, and other products from The MathWorks, visit www.mathworks.com or call 508-647-7000.

Other sources of information include:

• Complete MATLAB documentation: www.mathworks.com/access/helpdesk/help/helpdesk.shtml

• MATLAB Product Information: www.mathworks.com/products

• MATLAB Technical Assistance: www.mathworks.com/support

• MathWorks Store: www.mathworks.com/store

• MathWorks Home Page: www.mathworks.com

• Usenet Newsgroup: The comp.soft-sys.matlab news group provides a forum for professionals and students who use MATLAB and have questions or comments about it and its associated products.

See Also

Using MATLAB Script in Agilent VEE, MATLAB Script, MATLAB FAQ


Using MATLAB Script in Agilent VEE

VEE includes the MATLAB Script object, which gives you access to the functionality of MATLAB. VEE can pass data to the MATLAB Script Engine and receive data back, enabling you to include MATLAB mathematical functions in VEE programs.

note

If you already have MATLAB installed, you can choose to use your installed MATLAB to process MATLAB Script. However, if you do not have the Signal Processing Toolbox, you will not be able to use those functions from VEE. By default, VEE uses the MATLAB Script Engine shipped with VEE. To use your installed MATLAB, go to File => Default Preferences, under the MATLAB tab, check the Use MATLAB installed on your machine, and then select the version of MATLAB to use.

To use the MATLAB selected, you must save the configuration and restart VEE.

Some uses of the MATLAB Script object include:

• Letting MATLAB operate on VEE-generated data.

• Returning results from the MATLAB Script object and using the results in other parts of the VEE program.

• Performing sophisticated filter design and implementation in the MATLAB Script object by using MATLAB’s Signal Processing Toolbox functionality.

• Visualizing data using 2-D or 3-D graphs.

Following figure shows how a MATLAB Script object appears in a VEE program. When this program executes, it generates the data shown in the Alphanumeric object.

This figure shows the graph that is produced when the program runs.

When you include MATLAB Script objects in a VEE program, VEE calls the MATLAB Script Engine to perform the operations in the MATLAB Script objects. Information is passed from VEE to MATLAB and back again.

• Only some VEE data types are allowed as MATLAB script inputs. This is discussed in more detail in Working with Data Types and MATLAB Script.


MATLAB FAQ

Q: If I have MATLAB installed on a network server, can VEE pick it up?

A: VEE uses MATLAB engine library to interact with the standalone MATLAB. For Windows, it is not possible to use MATLAB on another machine via the MATLAB engine library now. Please refer to http://www.mathworks.com/access/helpdesk/help/techdoc/apiref/engopen.html.

Q: Can users go back to an older version of MATLAB if there are multiple versions installed?

A: Yes. Just go to Default Preferences->MATLAB and select the right version. VEE now takes control of which MATLAB to use. No need to pull up the command line and run matlab /REGSERVER.

Q: Is there a reason for not letting users call their own M files from MATLAB script objects?

A: It is the limitation of the new MATLAB engine. VEE 8.5 uses MATLAB Component Runtime as the built-in MATLAB engine. MATLAB Component Runtime can not execute unencrypted .m files. Please refer to http://www.mathworks.com/support/solutions/data/1-QXFMQ.html?solution=1-QXFMQ. However, if you select MATLAB installed on your PC (Default Preferences->MATLAB) instead of the built-in MATLAB engine, there is no such limitation.

If you copy the content of .m file and paste to the MATLAB script object, it will work in both scenarios (built-in engine or stand alone version).

Q:.Why does it take longer time to launch MATLAB initially compare to previous versions?

A: In previous VEE, the MATLAB engine is closed when a VEE program runs to the end; So if you run the program again, VEE needs to open the MATLAB engine again, that will be very slow. In VEE 8.5, the MATLAB engine is closed only when the VEE session is closed, so running MATLAB script will be much quicker after the first run.

At the first run, VEE needs to load the DLLs of the MATLAB and initialize the MATLAB environment, which is very slow, slower comparing to previous versions of MATLAB engine. However, that’s indeed outside of our control…

See Also

MATLAB Script, Using MATLAB Script in Agilent VEE


What is .NET?

Visual Studio .NET is Microsoft’s latest development platform. Unlike previous products, such as Visual Studio 6, .NET addresses the needs of both desktop programmers and Web developers. The strength of .NET from a VEE perspective is the .NET Framework's free runtime. The .NET Framework is distributed with VEE version 7.0 and higher. It is integral to several of the new features.

The key feature and benefit of the .NET Framework for VEE is the Framework class LIbrary (FCL). The FCL is of particular value to VEE programmers. There are 100's of new properties and methods that are now available through the Function & Object Browser. This new feature enables your code to derive functionality such as File and Directory management; simpler String management; simplified views of the Operating System environment; the manipulation of Web pages; access to Operating System processes; reading the registry; and many, many more.


.NET Terminology

As you review the topics describing .NET, you may find this list of Microsoft defined terms useful.

Assembly – Components are packaged in assemblies. Assemblies are the reusable, versionable, self-describing building blocks of .NET applications. The simplest assembly is a single executable that contains all the information necessary for deployment and versioning. An Assembly is the fundamental building block of the .NET Framework. It takes the form of an executable (.exe) or dynamic link library (.dll) file.

Primary Interop Assembly (PIA) – A primary interop assembly is a unique, vendor-supplied assembly that contains type definitions (as metadata) of types implemented with COM. There can be only one primary interop assembly, which must be signed with a strong name by the publisher of the COM type library.

Namespace – .NET Framework types use a dot syntax naming scheme that connotes a hierarchy. This technique groups related types into namespaces so they can be searched and referenced more easily. The first part of the full name — up to the rightmost dot — is the namespace name. The last part of the name is the type name. For example, System.Collections.ArrayList represents the ArrayList type, which belongs to the System.Collections namespace. The types in System.Collections can be used to manipulate collections of objects. (Nested namespaces are an exception to this rule. Please see MSDN documentation for more information.)

Reference – To use an Assembly, you must add a reference to it.

Shared Member – Shared members are properties, procedures, and fields that are shared by all instances of a class. Some programming languages refer to such items as static members.

Shared fields and properties are useful when you have information that is part of a class, but is not specific to any one instance of a class. Normal fields and properties exist independently for each instance of a class. Changing the value of a field or property associated with any one instance does not affect the value of fields or properties of other instances of the class. On the other hand, when you change the value of a shared field and property associated with an instance of a class, you change the value associated with all instances of the class. In this way, shared fields and properties behave like global variables that can be accessed only from instances of a class.

Class – If you are familiar with object-oriented programming, you know that a class defines the operations an object can perform (methods, events, or properties) and defines a value that holds the state of the object (fields). Although a class generally includes both definition and implementation, it can have one or more members that have no implementation.

An instance of a class is an object. You access an object's functionality by calling its methods and accessing its properties, events, and fields.

Instance Member – An instance member is tied to a specific instance of a class. Changes to its value affect the object it is associated with and no other objects.


VEE and the .NET Framework

Before beginning a review of how the .NET Framework interacts with VEE, review the .NET Framework by looking up the “.NET Framework – getting started” in the MSDN index.

Use

Under the Device menu there is a menu option called .NET Assembly References. As you will remember from the definitions, a reference allows you to use an Assembly. Open this menu selection. You will see a window similar to the following graphic:

There are a great number of assemblies you can select. These assemblies are located in the VEE home directory or in the directory where the .NET Framework is installed. If you are using an assembly that is not in one of these directories, use the Browse button to select it. There is also a checkbox for Importing Namespaces. Importing a namespace is equivalent to the using statement in C# or the Imports statement in Visual Basic.

The most commonly used assembly, mscorlib, is selected in the previous graphic. Go ahead and select this assembly. mscorlib encapsulates many functions useful to VEE users, such as file system manipulation, collection management, and data type conversion. Another very commonly used assembly is System, which contains functions such as process management, web request and response, and regular expressions.

Notice there is another tab labeled COM. Under this tab is a list of all the COM type libraries currently registered with your computer. In fact, this is the almost the same list of type libraries you see when you use the ActiveX automation references dialog box.

How do you know which of these two choices to use? You should use ActiveX if:

  • the library appears there

  • is fully functional

  • and has no Primary Interop Assembly (PIA).

This avoids adding another layer, the .NET Interop. You should use the .NET/COM interop if:

  • the library doesn't appear under ActiveX

  • or not all the functionality gets imported

  • or you know the COM library has a Primary Interop Assembly (PIA)

For example: not all IVI-COM drivers interfaces are visible from the Function & Object Browser's ActiveX Objects list. However, the .NET interop does allow you to see all of the IVI driver interfaces.

When using the .NET Assembly References menu option and selecting a COM type library from the list, VEE tries to import the COM type library as a .NET assembly. If there is a PIA, VEE uses it, otherwise VEE creates an Interop Assembly (or assemblies if the COM type library references other type libraries) in the directory where the program is saved. After VEE gets the Interop Assembly, it gets all the type information from that assembly.

Note

To avoid the overhead of VEE having to copy over the generated Interop Assemblies from a temporary directory to your VEE program directory, save your VEE program first. This way, the generated Interop Assemblies will be directly saved in your VEE program directory.

Go ahead and select the COM tab. This may take some time as VEE scans your registry for COM type libraries. Now select the Microsoft ActiveX Plugin.

You are now prompted for the namespace to import. This an optional step, but go ahead and select Interop.ActiveXPlugin, System, and System.IO.

Note

The Import .NET Namespaces dialog box will come up every time unless you uncheck the check box in the .NET Assembly References dialog box.

From the Device menu, open the Function & Object Browser. Select .NET/CLR Objects from the menu options. Note how the Assembly window reflects the two selections you made earlier.

All of the namespaces are listed in the Namespace window. All of the types are listed in the Type window and all the members of each type are listed in the Members window. Members include constructors, fields, properties, methods, and enumerations.

If you have used ActiveX in VEE, you will find that selecting a .NET class member is almost exactly the same process. The differences are minor and include:

1. COM did not have any shared (static) members. If the .NET member is a static member, the help area shows the STATIC keyword. The static icon ( [image]) also appears next to the member icon. To invoke a static member, you invoke on the class, not on an object instance. You can use the Function & Object Browser to get yourself familiarized with the syntax.

2. Instance object variables are generated with the first letter in lower case. This is a clue to you that you are dealing with an instance member. This also means you need to declare and initialize a variable if you haven't already done so.

3. To create a .NET object, select the constructor (constructors and methods share this icon [image]) in the member list. As in the previous graphic, the Create Instance button is available. Selecting this button generates a formula template for creating a new .NET object. You can connect to the dateTime output pin in the following graphic to any input pin of any formula box that requires this .NET object as input.

4. The Enums ( [image]) in .NET are strongly typed, so you can no longer substitute an integer constant for an Enum like you did with ActiveX objects. You have to enter the full Enum name (minus the namespace if you have imported it) or use the Create Formula button and save yourself some typing. For examples, see Enum related examples in the examples\dotnet directory.

See Also

Importing a Namespace in VEE, .Net Operation Builder, .NET Examples


Importing a Namespace in VEE

Importing a Namespace into VEE Pro

Namespaces qualify a type by creating a template for static members or enumerators and thereby eliminating the need for a type prefix.

Use

Importing a namespace is the same as using the Imports statement in Visual Basic or the using statement in C#. In both cases, you will not have to qualify the use of a type from that namespace. VEE supports two methods for importing a namespace.

The first method is by using the checkbox on the .NET Assembly References menu choice as shown in the graphic below:

The second method is to select the Import .NET Namespaces option from the Devices menu. A full list of .NET namespaces is listed and, to import one, just select the checkbox beside it.

If the assembly you select has no namespaces, the list will be empty.

If you have not imported a namespace for a class, the static members and enumerations for that class will be fully qualified by VEE's Function & Object Browser's Create Instance button automatically. This will make your formula boxes much larger.

Examples

See DateTime.vee and FileInfo.vee


.NET Operation Builder

The .NET Operation Builder helps you select .NET types for use in your VEE programs.

Use

As shown in the graphic below, the .NET Operation Builder makes it easy to select a .NET namespace and Type, and, subsequently the methods, properties, and fields that are part of it.

To use the .NET Operation Builder, first select the .NET assemblies you want to work with by using the Device [image] .NET Assembly References. These assemblies (mscorlib in this case) are then displayed in the .NET Operation Builder dialog box. Select the namespace you want (System.IO in this case). Next, select the Type you need by using the .NET Operation Builder to drill down to the specific class (Directory in this case), enumeration, or interface you want to use.

A much quicker way to find the type you want is to click on the Find toolbar button. This opens the Find a Type windows on the right side of the dialog. You may simply type in the type name or a sub-string of the type name that you are looking for and hit Enter. VEE displays the results in a list view. You can then double-click on one of the results to directly jump to the type in the tree view on the left.

Once you have selected the Type you want to work with, a VEE object is placed on the VEE work area, and prompts you to add an operation. Double click as shown in Selecting a .NET Member, and you are prompted to select a member from the Directory class.

See Also

Selecting a .NET Member, Editing a .NET Member, and Using .NET Controls

Location

Devices [image] .NET Operation Builder


Selecting a .NET Operation

Once you have selected the Type you want to work with, a VEE object appears. Place it on the VEE work space and double-click as shown in the next graphic. You are prompted to select an operation from the Directory class.

Notice there are three icons at the top of this dialog box. The Create icon narrows the list to show only the available CreateInstance constructors, which are used to create a new instance of the selected type. The Declared Only icon shows only the members that are declared by this type, and the All icon shows all members that are declared by this type or inherited from its parent types.

Choose the CreateDirectory member.

Once you select the CreateDirectory member, you need to configure it. In the two graphics shown in Editing a .NET Member, you can see the configuration tabs for the method.

Location

Devices [image] .NET Operation Builder


Editing a .NET Operation

Once you have selected an operation, you have to edit it to provide the additional information needed to complete its task.

Use

After completing the tasks described in .NET Operation Builder and Selecting a .NET Member, you need to configure the CreateDirectory operation. In the following two graphics, you can see the configuration tabs for the method. In the Edit Parameters tab, you type in the path for the new directory. Note: \ is a special character. Use \\ or / for a path separator. For example, C:\\Program Files/Agilent. If you hit the Tab key, you can see the code that VEE will generate.

In the Configure Terminals tab, you configure the names of your variables. You may also specify different names other than the default generated by VEE and whether VEE should add a terminal to the object. Generally, you do not need to change these settings.

If you have followed all of the steps described in .NET Operation Builder and Selecting a .NET Member, you can select OK; run the program; the directory is created; and you are done.

You may also double-click on an existing operation in the .NET Operation Builder. This brings up the Edit Operation Dialog, which lets you make any modifications to the existing operation.

See Also

Selecting a .NET Member and .NET Operations Builder

Location

Devices [image] .NET Operation Builder


.NET Control Host

A VEE object that hosts a .NET control added to the VEE work area.

Use

The .NET Framework ships a number of standard controls and you may also choose to use a third-party control. To use a standard control, you just go to the Device [image] Windows Forms Controls menu and select a control from the list.

For a third party control, see the menu selection Device [image] Additional .NET Controls. If you have selected the assembly with the third party control using the .NET Assembly References dialog, the control will automatically appear on this menu.

The .NET Control Host is used as a container for a .NET control. When you add a control to the work area, VEE creates the container so you have access to the control that is similar to the access available to other VEE objects. The container also gives you access to the control’s specific properties built into it by the control’s developers.

When a control appears in the work area, it has a title and variable name in its title bar. It does not have pins that let you connect it to other objects using lines. You must use expressions referring to the variable name that manipulate the control by getting and setting its properties, and calling methods. You can still use the Function & Object Browser (Device Function & Object Browser) to help you generate these expressions in Formula objects, but the new .NET Operation Builder object will make the task much simpler. Just select “Generate .NET Operation Builder” from the control’s context menu. See .NET Operation Builder for more details. The variable name essentially is the declared variable name of the control. The control’s declared variable name is very similar to a variable created using the Declare Variable object, except that the control’s variable is already initialized. The declaration is local-to-context, so by default, the variable name can only be used in the context in which it exists. For information about accessing the .NET control globally, see Notes below.

Object Menu

  • Help - Opens this VEE Help topic that describes the container object.

  • Properties - Provides access to the VEE container object’s properties such as title, variable name, assembly name and .NET type.

  • Control Properties - Provides access to the control’s property grid that is populated automatically by all the properties of the control. Every kind of control has different properties. The edits to the control properties are not reversible. You would have to delete and recreate the control to restore the default. Some control properties cannot be serialized (saved) into VEE program and you will get warnings for those properties.

  • Edit Event Handler… - Opens the Edit Event Handler dialog box if any event-handler UserFunctions have been created for the control.

  • Create Event Handler… - Opens the Create Event Handler UserFunction browser. This browser lets you create a UserFunction to handle an event generated by the control. You can create an event handler for each event listed in the browser’s Member area.

  • Generate .NET Operation Builder – Generates the .NET Operation Builder for this type of control.

Properties (container object)

Title - Displays the container object’s current title and allows you to edit it.

Name - Displays the control’s current local variable name and allows you to edit it. This declares and initializes the control as a local-to-context variable.

.NET Type – the type of the control

Assembly – the assembly that contains the control

Notes

VEE must be set to VEE 6 or higher execution mode for .NET support to take effect (Default Preferences). .NET controls are available as individual products or may be installed as part of a larger application.

VEE does not support all .NET controls. If a control is incompatible with VEE, an error will occur when you add the control to your program or while you are using it. There may also be some less obvious issues like below:

  1. Not all controls listed in Device [image] Windows Forms Controls menu are suitable to be placed on VEE work area directly. Some controls are meant to be contained inside other controls. For example, a Splitter is meant to be used inside a container control like Panel. In that case, you should only place the container control on VEE’s work area, and then add the child controls to the container control with Formula or .NET Operation Builder. See Splitter.vee for an example.

  2. Some control methods like ProcessDialogKey, ProcessDialogChar, ProcessCmdKey are only called when the control is hosted inside a Windows Form application, but a VEE application is not a Windows Form application. A control writer will seldom need to implement these methods, but if he or she does, the VEE program may not offer all of the functionality of that control, or you may get unexpected behavior.

  3. When you change the control properties through the Control Properties dialog, the properties are serialized (saved) into the VEE program. VEE does not explicitly control the order of serialization. So if a .NET control has properties that are highly coupled, e.g., setting property A will change the property B, then you may not get the exact expected result when restoring a control from its saved state. In this example, depending on whether B is saved/loaded before A, you may get a different result. Although this is uncommon, if you do want to avoid the dependency on the order of serialization, you should write the expressions using the Formula object or .NET Operation Builder object to change the control properties. This way, you can control the order explicitly.

When you add a control to the VEE work area, it appears with an assigned local variable name in its title bar. You can change the assigned variable name by changing the Name property of the .NET Control Host. Since the control has no pins to connect with lines to other objects in your program, you must manipulate the control using expressions in Formula objects or the .NET Operation Builder that refer to the control by its variable name. Since the variable is local-to-context, these expressions must appear in the same context as the control.

If you want the variable name to be global, then declare a new variable name using Declare Variable (Data [image] Variable [image] Declare Variable). Since the control’s variable name already exists, you cannot simply declare it as global; VEE does not allow such conflicts. In Declare Variable, enter the variable name, set Scope to Global, and set Type to Object. You do not need to check Specify Object Type; however, by specifying the object type details, VEE will do type checking automatically to assure that the specified Assembly and Class are assigned only to the declared variable. Then you can set the control’s local variable (such as progressBar1) equal to the declared variable (such as g_progressBar1) as shown in this expression:

Set g_progressBar1 = progressBar1

See Also

.NET Operation Builder

Location

Device [image] .NET Controls


VEE and PIAs

VEE and Primary Interop Assemblies

You already know from the topic ".NET Terminology" that a PIA is “...a unique, vendor-supplied assembly that contains type definitions (as metadata) of types implemented with COM. There can be only one primary interop assembly, which must be signed with a strong name by the publisher of the COM type library.” How does VEE make these PIAs available to you?

When you choose the COM tab in Device > .NET Assembly References, VEE goes through the registry and finds all registered COM type libraries on your machine. As you select COM type libraries, if the library has a PIA and the PrimaryInteropAssemblyCodeBase key for the COM type library is registered, then the PIA location is shown in the description area. Note that PrimaryInteropAssemblyCodeBase is only registered when the PIA is registered with /codebase option. Not all PIAs are registered this way. Currently, all Agilent IVI-COM drivers are registered with the /codebase option, but many assemblies are not. Also note that when you check a COM type library, all VEE does is to look at the registry, it does not load the interop assembly if there is one. Once you choose OK, if there is no PIA, then VEE will generate one or more Interop Assemblies automatically.

If you choose browse and select a PIA or an Interop Assembly directly, however, VEE actually loads the interop assembly in order to find out which COM type library it belongs to and whether it is a primary interop assembly or not, which is the key difference between browse/select and just a check on the COM tab list. After the interop assembly is loaded, VEE finds out which COM type library it belongs to and then checkmarks the corresponding COM type libraries under the COM tab list.


Programming .NET

Typing

A new type conversion function called asClrType has been added. AsClrType converts a VEE data type to .NET/CLR data type. The valid .NET/CLR data types include all of the primitive types (Boolean, Byte, Sbyte, Int16, Uint16, Int32, Uint32, Int64, Uint64, Char, Double, and Single), Decimal, Date/Time and String. An error will be thrown if the .NET data type is not valid or the conversion fails.

asClrType is rarely needed as VEE converts between VEE and .NET data types automatically most of the time. It’s only needed when you have to use a specific .NET data type that’s not natively supported in .NET or if you want to use a VEE data type like a .NET object, for example, in order to invoke the .NET object methods. For example, VEE converts between .NET String and VEE Text data types automatically, but if you want to use the many useful String functions provided by .NET, you will need to convert the VEE Text to a .NET String object first.

The .NET and Win32 APIs

For an excellent comparison of these two APIs see, http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dndotnet/html/win32map.asp

Programming Practices

Installing a New Assembly

Please review the .NET Terminology topic if assembly is a new term for you. Public assemblies must be installed in the Global Assembly Cache (GAC). The assemblies installed in the (GAC) are seen by all the applications on your computer. (Please refer to MSDN for more details.) Once the shared assembly is updated, you can reference it by choosing the Browse button and browsing to the original location of the assembly before it was installed in the GAC.

Most assemblies are not installed in the GAC. They are private assemblies. A private assembly should be located with the VEE program that references it. The first time you use the .NET Assembly References dialog box to browse and select a private assembly, VEE will copy it over to the same directory as your current VEE program if it is not already located there. This copying also makes distributing your VEE program easier and is known as xcopy deployment.

Updating an Assembly

If you have already referenced the shared assembly in your VEE program, you need to do a File/New or restart VEE again before the new version of the shared assembly will be loaded by VEE. If it is not a shared assembly but a private assembly, you need to do a File/New or restart VEE after manually copying the new version of the private assembly into your current VEE program directory.

Calling an Instance Method

When calling an instance method, it is easy to forget to declare and create the .NET object first. To avoid this problem, it is recommended that you use the Function & Object Browser and the Create Instance button to generate the constructor formula template first.

In the figure below, fileInfo is declared locally and initialized as System.IO.FileInfo object. You can wire the fileInfo output pin to the input pin of any subsequent formula boxes that require this object instance. Also note, that both the CreateInstance and the fileInfo.LastAccessTime formula boxes are created by VEE automatically. All you need to do is wire them together and provide any additional parameters.

Calling a Shared/Static Method

When you call a .NET member, if the member is Shared/Static, the word STATIC appears in the Function & Object Browser description box. Static methods are called from a .NET class directly, not from an object. Thus you do not need to create a .NET object first. The following graphic is an example of a static method with the namespace imported.

Tips

  • If you are calling a .NET method requiring a Long/Single/Double.../ from a VEE formula box where the parameter comes from an input pin, say 'A', you can often eliminate a 'Method Not Found' exception by simply double-clicking input pin A, and setting the required type to match: int32/Real32/Real64/etc.. This is easier than calling the built in asCltType function or the .NET System.Convert.To* functions.

  • The formula template generated for Instance members always begin with a lower case letter. Static members have a fully qualified name (namespace plus classname) unless their namespace has been imported.

  • When you call a .NET member, if the member is Static, the word Static appears in the description box of the Function & Object Browser. Static methods are called from a .NET class directly, not from an object. Thus, you do not need to create a .NET object first.

  • Enums in .NET are different from enums in COM. They are strong typed. There are two types of enums in .NET, one is treated as an enumeration of constants, the other is treated as bit fields. Only the latter type of enums are intended for bitwise operations. In VEE, both types of enums will have their underlying integral value displayed in the description area of the Function & Object Browser. You can use bitOr, bitAnd, etc. on the latter type of enums as in the VEE example, examples\dotnet\FileAttributes.vee.

  • There is a new Copy to Clipboard button in the Function & Object Browser. You can use this button to copy a formula text into the clipboard, and later paste it anywhere in a formula box. This is especially useful when you want to have multiple formula statements inside of one formula box.

Limitations

VEE does not support the creation of .NET Delegates

Examples

For an example of asClrType, see StringSplit.vee.

For an example of calling an Instance and Static methods, see FileInfo.vee

For other examples of .NET programs, see .NET Examples.


Converting VEE Data Types to .NET

Converting VEE Pro Data Types to .NET

VEE converts data types between VEE and .NET automatically for all data types that both VEE and .NET natively support. For example, Int16, Int32, Real64, etc. You may wish to undo this automatic conversion so you can use the data as a true .NET object. In those cases, you can use the new asClrType type conversion function to convert a VEE data type to a .NET/CLR type. See the conversion tables below for more details.

Use

.NET operations in VEE will usually accept a precision-widening (type promotion) data type as a parameter, but not a precision-narrowing (type demotion) data type. For example, you may pass VEEs UInt8 to a .NET operation that requires a parameter of type System.Int16, but not the other way around. Also, if the .NET operation requires a ByRef parameter and you want to retrieve its result back, then the data type has to be match exactly. For example, if the .NET method requires a parameter of type ByRef Int32, then you can only pass VEEs ByRef Int32 data type. If you don't care about retrieving the result back, then you may skip the ByRef keyword and the normal parameter rule would apply.

The following tables illustrate the data type conversion functions between VEE and .NET.

For an example of how to use asClrType, see StringSplit.vee.

Tables

Table 1 - Converting .NET scalar data types to VEE data types in VEE 8.5

Convert From .NET Data Type | Convert To VEE Data Type | Notes
System.Boolean | Int16 | Use isVariantBool() to determine if the VEE Int16 was of type System.Boolean
System.Byte | UInt8 |
??? | UInt16 |
System.Char | Object | You can use a System.Convert.To* method to convert it to a .NET data type that VEE can convert automatically, e.g., ToInt32().
System.DateTime | Object | See examples\dotnet\DateTime.vee.
System.Decimal | Object | You can use a System.Convert.To* method to convert it to a .NET data type that VEE can convert automatically, e.g., ToInt32(). If the value does not fit in an Int32, an error 751 will occur indicating a System.OverflowException. The System.Decimal structure itself also provides a number of conversion methods.
System.Double | Real64 |
System.Enum | Object | See examples\dotnet\FileInfo.vee.
System.Int16 | Int16 |
System.Int32 | Int32 |
System.Int64 | Int64 |
System.SByte | Object | You can use a System.Convert.To* method to convert it to a .NET data type that VEE can convert automatically, e.g., ToInt16().
System.Single | Real32 |
System.String | Text | VEE automatically converts String to Text. If you want to use the many useful functionalities in the System.String class, you may use asClrType to convert the text back to System.String, e.g., Set dotNetString = asClrType(veeText, System.String); ModifiedString = dotnetString.Replace( ,_); Also see examples\dotnet\stringsplit.vee for an example
System.UInt16 | Object | You can use a System.Convert.To* method to convert it to a .NET data type that VEE can convert automatically, e.g., ToInt32().
System.UInt32 | Object | You can use a System.Convert.To* method to convert it to a .NET data type that VEE can convert automatically, e.g., ToInt32(). If the value does not fit in an Int32, an error 751 occurs indicating a System.OverflowException.
System.UInt64 | Object | You can use a System.Convert.To* method to convert it to a .NET data type that VEE can convert automatically, e.g., ToInt64(). If the value does not fit in an Int64, an error 751 will occur indicating a System.OverflowException.
System.Object | Object |

Table 2 - Converting VEE data types to .NET scalar data types in VEE 8.5

Convert From VEE Data Type | Convert To .NET Data Type | Notes
Boolean | System.Boolean | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Int16 | System.Int16 | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Int32 | System.Int32 | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Int64 | System.Int64 | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Real32 | System.Single | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Real64 | System.Double | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Text | System.String | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
UInt8 | System.Byte | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
UInt16 | ?? |
<scalar of type *> | System.Boolean | Use asVariantBool() on any scalar VEE data type that can be cast to an Int16, (UInt8, Int16, Int32, Real32, Real64, Text). You may also use the more generic asClrType, e.g., asClrType(veescalar, System.Boolean).
Date/Time | System.DateTime | VEEs Date/Time is stored as type Real64. Use asClrType(veeDateTime, System.DateTime). See examples\dotnet\DateTime.vee.
Object | System.Object | If VEE holds a pointer to a .NET Object.

Table 3 - Converting .NET array data types to VEE data types in VEE 8.5

Convert From .NET Data Type | Convert To VEE Data Type | Notes
System.Boolean Array | In16 Array | Use isVariantBool() to determine if the array was of type System.Boolean
System.Byte Array | UInt8 Array |
??? | UInt16 Array |
System.Char Array | Object | The VEE object holds a pointer to a System.Array .NET object. You can use the formula CreateInstance(mscorlib,System.String,charArray).ToString(); to convert an array to a .NET data type that VEE can convert automatically.
System.DateTime Array | Object | The VEE object holds a pointer to a System.Array .NET object.
System.Decimal Array | Object | The VEE object holds a pointer to a System.Array .NET object. You can use a System.Convert.To* method to convert each array member to a .NET data type that VEE can convert automatically, e.g., ToInt32().If the value does not fit in an Int32, an error 751 occurs indicating a System.OverflowException. The System.Decimal structure itself also provides a number of conversion methods.
Double Array | Real64 Array |
System.Enum Array | Object | The VEE object holds a pointer to a System.Array .NET object.
System.Int16 Array | Int16 Array |
System.Int32 Array | Int32 Array |
System.Int64 Array | Object | The VEE object holds a pointer to a System.Array .NET object. You can use a System.Convert.To* method to convert each array member to a .NET data type that VEE can convert automatically, e.g., ToInt32(). If the value does not fit in an Int32, an error 751 occurs indicating a System.OverflowException.
System.SByte Array | Object | The VEE object holds a pointer to a System.Array .NET object. You can use a System.Convert.To* method to convert each array member to a .NET data type that VEE can convert automatically, e.g., ToInt16().
System.Single Array | Real32 Array |
System.String Array | Text Array | VEE automatically converts String to Text. If you want to use the many useful functions in the System.String class, you can use asClrType to convert the text array back to a System.String array.
System.UInt16 Array | Object | The VEE object holds a pointer to a System.Array .NET object. You can use a System.Convert.To* method to convert each array member to a .NET data type that VEE can convert automatically, e.g., ToInt32().
SystemUInt32 Array | Object | The VEE object holds a pointer to a System.Array .NET object. You can use a System.Convert.To* method to convert each array member to a .NET data type that VEE can convert automatically, e.g., ToInt32(). If the value does not fit in an Int32, an error 751 occurs indicating a System.OverflowException.
System.UInt64 Array | Object | The VEE object holds a pointer to a System.Array .NET object You can use a System.Convert.To* method to convert each array member to a .NET data type that VEE can convert automatically, e.g., ToInt32(). If the value does not fit in an Int32, an error 751 will occur indicating a System.OverflowException..
System.Object Array | Object | The VEE object holds a pointer to a System.Array .NET object.

Table 4 - Converting VEE array data types to .NET data types in VEE 8.5

Convert From VEE Data Type | Convert To .NET Data Type * | Notes
Int16 Array | System.Int16 Array | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Int32 Array | System.Int32 Array | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Real32 Array | System.Single Array | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Real64 Array | System.Double Array | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
Text Array | System.String Array | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
UInt8 Array | System.Byte Array | Use asClrType to convert to other .NET/CLR types. See asClrType documentation.
UInt16 Array | ??? |
< type *> Array | System.Boolean Array | Use asVariantBool() on any VEE data type that can be cast to an Int16, (UInt8, Int16, Int32, Real32, Real64, Text). You may also use the more generic asClrType, e.g., asClrType(veeArray, System.Boolean).
Date/Time Array | System.DateTime Array | VEEs Date/Time is really of type Real64. Use asClrType(veeDateTimeArray, System.DateTime). See examples\dotnet\DateTime.vee.
ref, out, ByRef | Either scalar or array of the type indicated by the mapping table above | Use the VEE keyword ByRef. Not using the ByRef keyword will not cause a .NET operation exception, but the passed-in parameter will not be changed. This is probably not what the .NET class designer intended.

Notes

There is a known issue with VEE code template generation for calling .NET methods. VEE only generates the keyword “ByRef” when a parameter of a .NET method is explicitly declared as “Ref” or “Out” in C# or “ByRef” in Visual Basic .NET. Every time a “ByRef” keyword is specified, VEE will allocate extra memory to receive the data returned from server. This known issue becomes a problem when these conditions are met:

1. The parameter type is one of the array types that VEE supports - Text array, UInt8 array, Int16 array, Int32 array, Real 32 array, Real 64 array.

2. The .NET server did not explicitly declare the parameter as “Ref” or “Out” in C# or “ByRef” in Visual Basic .NET.

3. The .NET server actually changes the value of the parameter inside the method.

If all the above conditions are met, the VEE user would have to add the “ByRef” keyword manually in front of the parameter in order to get the changed value back from the .NET server.


.NET and IVI Drivers

What is IVI? IVI is a new instrument driver standard being developed by the IVI Foundation. The IVI Foundation is a consortium established to promote specifications for programming test instruments. These specifications provide multiple benefits but primarily make instrument interchangeability simpler. For a review of the IVI Foundation, go to http://www.ivifoundation.org/.

Why would I want to use an IVI-COM driver? Assume two vendors provide an IVI-COM driver for a DMM. To meet the IVI standard, the base drivers must be interchangeable. This means that whichever driver you use on your system, the DMMs from either vendor will work. Your code is reusable without any intervention.

Use

How do I make IVI-COM drivers available to VEE? Install the IVI-COM drivers. To find drivers for your instruments, go to http://www.agilent.com/find/adn. If you are an ADN member, select Downloads from the menu > Drivers by Driver Type > IVI-COM Drivers and Components. Be sure to download and install the IVI-COM Shared Components before installing IVI-COM drivers. Also, be sure to select the button labeled "Install PIA's" on the Shared Components installer. If you are not an ADN member, it is an online source for Agilent drivers, evaluation software, documentation, and white papers. To sign up for this free service, fill out the registration form for new users.

Once the IVI-COM drivers are registered on your system, they are available just like any other COM component and, like most COM components, will appear on the COM tab of the Device > .NET References in VEE.

They can also be accessed through the Instrument Manager by selecting the interface, then Advanced Properties, and finally, editing the IVI-COM Driver tab. You can then choose the instrument, click the IVI Driver button and create a To/From transaction box.

How do VEE and .NET make IVI-COM drivers available? Through .NET’s interop technology. Via the interop, the IVI-COM drivers become available to VEE. If there isn’t a primary interop assembly available for a COM DLL that you select, VEE attempts to generate an Interop Assembly (or more than one if the COM .dll references other type libraries). VEE then adds the Assembly Reference to the Function Object Browser’s .NET Object Assembly References list. At this point, the IVI-COM driver can be invoked just like any other COM type library.

Examples

Agilent recommends that you use the Device > .NET Assembly References COM tab rather than ActiveX. It will supply more of the types necessary for the use of the IVI driver. The Notepad for these examples is very helpful and should be explored fully. There are other examples also in ~installdir\examples\ivi-com.

AgilentSA.vee and AgilentRFPowerMeter.vee

See Also

What is IVI?, .NET and COM, To/From IVI-COM, To/From IVI-COM - Advanced, and COM Objects - Troubleshooting


VEE and .NET Security

VEE versions 7.0 and higher depend upon the .NET Framework and the CLR. There is one security issue to consider for network installations. If you install VEE on a network drive,

  1. Open a command prompt. Go to your system drive (usually C).

  2. Change directory to \[winnt or windows]\Microsoft.NET\Framework\v2.0.50727.

  3. From the prompt run the following command:

Caspol –machine –addgroup “All_Code” –url File://[VEEInstallDir]/* FullTrust

The VEEInstallDir is your VEE installation directory on a network drive. (Caspol ships with the .NET Framework and is installed when VEE is installed.) You may also run the .NET Framework Configuration Wizard to achieve the same result. You must have administrative privileges to run either tool.

In addition to this, if your VEE program references .NET assemblies, VEE often needs to generate and/or save assemblies to an accessible location. So for example, if you open a VEE program with .NET references from email or a network without saving locally first, you might get a warning.

Note

If a custom .NET (not an assembly in the .NET Framework 2.0) is to be used from a VEE application, a Security Exception will occur if the custom .NET is not located on a local drive.

To avoid such problem, use one of the following methods :

  1. Copy the custom .Net to a local drive,

  2. Use caspol as mentioned above,

  3. Run the .Net Framework Configuration in the Start Menu => Control Pane =>Administrative Tools and increase trust for the appropriate zone.


Selecting ActiveX Controls

Before you can use ActiveX controls in VEE, you need to inform VEE which ActiveX controls you want to use. Click Device [image] ActiveX Control References... The resulting ActiveX Control References dialog box lists the available control type libraries registered by the Windows Registry. The following figure shows the dialog box with several selected controls.

Your list is probably different depending on the applications or controls you have installed. Controls can be installed individually or as part of other application installations. When you highlight a control name, its location appears in the dialog box status area.

When you find the control you want to use, click the check box by the control name (or double-click the name itself) so a check mark appears. Then, click OK to load them into memory for use in VEE and to search for their object classes, dispatch interfaces, and exported events. You can select multiple controls, but you should select only the ones you plan to use since selected libraries use memory.

If you know a control type library exists for a control, but it does not appear in the list, it is possible the library did not get registered during its installation. Press the Browse button to find the type library missing from the list. When you locate and open the type library file, VEE will attempt to register the type library and add it to the list.

See Also

Adding a Control to VEE, Using an ActiveX Control in VEE, Manipulating ActiveX Controls


Adding a Control to VEE

Adding a control to a VEE program is similar to adding any other object. After you select the ActiveX control(s), you can add them to your program. Click Device [image] ActiveX Controls to view a cascading menu listing the selected controls. See the following figure for an example.

note

In this figure and the figure above, five controls are selected in the ActiveX Control References dialog box, but six appear in the Device [image] ActiveX Controls cascading menu. It is normal for some selections to result in more than one ActiveX control being added to the resulting menu.

Select a control and place the resulting object in a detail view in the VEE work area. You can place controls in any context – Main, UserObject, or UserFunction. You can delete controls by selecting Cut from their object menu or double-clicking the object's context menu button. See the figure below.

Differences in the ActiveX Control Host

ActiveX controls are different from any other VEE object. Unlike all other VEE objects, ActiveX controls have no input or output pins nor do they have any sequence input or output pins. Controls are not data flow oriented.

To give you access to a control that is similar to the access available to other objects, VEE creates a special container in the program that is the host for the control. The container also gives you access to the control’s specific properties built into it by the control’s developers. Regardless of the combined features, we refer to these as ActiveX controls.

Some differences in the object menu follow. The Properties and Control Properties menu items provide access to two different sets of properties. The host container’s properties are separate from the control’s properties. To see the typical properties associated with VEE objects, in this case the host container, click Properties. To view and change the ActiveX control’s properties that are provided by the control’s developer, click Control Properties.

The Help button on the control’s Properties dialog box opens the online help for that control if the developer provided one. The object menu’s Help item opens the VEE Online Help topic for the host container. Create Event Handler... and Edit Event Handler... provide the same functionality as described for ActiveX automation objects in Handling Automation Object Events.

See Also

Selecting ActiveX Controls, Using an ActiveX Control in VEE, Manipulating ActiveX Controls


Using an ActiveX Control in VEE

When you add a control to the VEE work area, the control appears with an assigned local variable name in its title bar. You can change the assigned variable by double-clicking the control’s title bar to get the ActiveX Control Properties dialog box. Under the General tab, change the value beside Name:.

Since the control has no pins to connect with lines to other objects in your program, you must manipulate the control using expressions in Formula objects that refer to the control by its variable name. These expressions must appear in the same context as the control, since the control’s variable name is scoped "local to context".

Using the Assigned Local Variable

If you add a Calendar control to your program, it is assigned the local variable name Calendar. The title bar contains Calendar. To interact with the control, add a Formula object that is in the same context as the Calendar control. The following examples demonstrate setting a property, getting a property and calling a method on the ActiveX control referenced by the VEE local variable called Calendar:

Calendar.Day = 24;

Month = Calendar.Month;

Calendar.AboutBox()

Declaring a Global Variable for a Control

If you want the variable name to be global, declare a new variable name using Declare Variable (Data [image] Variable [image] Declare Variable). This is similar to the variable declaration described in Declaring Automation Object Variables. Since the control’s variable name already exists, such as Calendar, you cannot declare it as global as VEE does not allow such conflicts. A common naming convention is to adapt the local variable name (as in g_localName), resulting in g_calendar.

In Declare Variable, enter the new variable name, set Scope to Global and set Type: to Object. You do not need to check Specify Object Type to specify the particular Library and Class. However, if you do so, VEE will do type checking automatically to assure that the Library and Class are assigned only to the declared variable.

After declaring the global variable, use a Formula expression to set the control’s local variable name (such as Calendar) equal to the declared variable name (such as g_calendar). It is important to use the SET keyword, as shown in this expression:

SET g_calendar = Calendar

See Also

Selecting ActiveX Controls, Adding a Control to VEE, Manipulating ActiveX Controls


Manipulating ActiveX Controls

Setting and getting properties, calling methods and handling events for an ActiveX control uses the same mechanisms described for ActiveX automation objects in Manipulating Automation Objects and in Handling Automation Object Events.

Although VEE contains ActiveX controls in host objects so they are accessible, the control’s behavior is slightly different when a program runs. Basically, controls are viewable in only one place at a time – either the detail view or panel view.

As an example, suppose a control is added to a program’s detail view and the program dynamically displays a panel on which the control appears using Show Panel on Execute or showPanel(). The control is blanked out in the detail view until the panel closes. When the panel closes, the control reappears in the detail view.

See Also

Selecting ActiveX Controls, Adding a Control to VEE, Using an ActiveX Control in VEE


Using ActiveX Automation in VEE

ActiveX automation lets you use VEE as an automation controller to control other Windows applications such as Microsoft Word, Excel, Access, and Crystal Reports. You can perform such activities as sending data to the applications for report generation and reading data back from them. For automation-capable applications, this supersedes Dynamic Data Exchange (DDE).

ActiveX controls are available from various vendors. They extend VEE functionality by providing domain-specific services via ActiveX automation properties, methods, and events. Most ActiveX controls also provide a user interface that lets you manipulate a control such as a "slider" to input a value into a program, just as you would do with an VEE Slider object.

VEE does not support all ActiveX controls. If a control is incompatible with VEE, an error may occur when you add the control to your program or while you are using the control. Controls that are known to not work properly are listed in here.

note

To enable ActiveX support, you must set VEE to VEE 5 or higher Execution Mode in the Default Preferences dialog box, under the General tab. VEE 8 is the default mode for new programs. The status bar at the bottom of VEE’s window displays the current mode. If you are adding ActiveX functionality to a program developed in VEE Versions 3.x, 4.x, or 5.x, make sure your program runs in VEE 5 or higher Execution Mode before adding new features. See Tell me about.. Execution Modes in Contents and Index under Help menu for more information.

Several examples are available that demonstrate the use of ActiveX automation and ActiveX controls. They are located in the VEE installation directory under \examples\ActiveXAutomation and \ActiveXControls. To open and run these examples use Help [image] Open Example... .

See Also

Making Automation Objects Available in VEE, Declaring Automation Object Variables, Creating an Automation Object in a Program, Using Distributed Component Object Model (DCOM), Getting an Existing Automation Object, Manipulating Automation Objects, Data Type Compatibility, Deleting Automation Objects, Handling Automation Object Events


Making Automation Objects Available in VEE

When you install Windows applications, it is very likely that ActiveX type libraries are also installed that allow the applications to act as automation servers. Type libraries describe the capabilities of an ActiveX object and are available for use if they exist on your system. You may prefer to select specific type libraries in VEE for the following reasons:

• To have VEE perform type checking on variables declared for ActiveX objects where the object type is defined (see Declaring Automation Object Variables).

• To catch events generated by an automation object (see Handling Automation Object Events).

• To view information in the ActiveX Object Browser (see Using the ActiveX Object Browser).

To select the type libraries you want to reference in a program, click Device [image] ActiveX Automation References… The ActiveX Automation References dialog box appears listing all type libraries registered by the Windows Registry. The following figure shows the dialog box with the Microsoft Access library selected for use.

Your list is probably different, depending on the applications you have installed. When you highlight a library name, its location appears in the dialog box status area. When you find the automation server you want to use, click the check box by the library name (or double-click the name itself) so a check mark appears. Then, click OK.

This loads the selected type library and searches it for the object classes, dispatch interfaces, and events that it exports. You can select multiple libraries, but you should select only the ones you plan to use since selected libraries use memory.

If you know a type library file exists for an automation server, but it does not appear in the list, it is possible the type library was not registered when the associated application was installed. Press the Browse button to find the type library missing from the list. When you locate and open the type library file, VEE will attempt to register the type library and add it to the list.

See Also

Using ActiveX Automation in VEE, Declaring Automation Object Variables, Creating an Automation Object in a Program, Using Distributed Component Object Model (DCOM), Getting an Existing Automation Object, Manipulating Automation Objects, Data Type Compatibility, Deleting Automation Objects, Handling Automation Object Events


Declaring Automation Object Variables

You can declare a variable for an ActiveX automation object using the new Object data type (Data [image] Variable [image] Declare Variable). The declared variable is a reference to an object that lives in another process. For instance, it might point to a ComboBox in Access. As shown in the figure below, when you set the variable Type to Object and the Sub Type to COM, the dialog box expands to list the library name, class, and enabled events.

You can specify the object variable’s type further by clicking the Edit button to access the Specify Object Type dialog box that lets you set the library and class names and enable events available for the class.

If you are using the Access Object Library, you can declare a variable combo, then specify the object type as Library: Access and Class: ComboBox as shown below. In this example, the class ComboBox contains events. To use the events, click Enable Events. If events are not available for a class, the checkbox is grayed out.

After specifying the object type, click OK to dismiss the dialog box and return to Declare Variable, which displays the information.

If you enable events, you can create an event-handler UserFunction for each event that you want to catch. For information about using events, see Handling Automation Object Events.

As with any VEE variable, declaring a variable is optional and doing so does not create the automation object in the program. However, if you declare variables for automation objects and specify the object type details, VEE does type checking automatically to assure that only objects of the specified Library and Class type are assigned to the declared variable.

See Also

Using ActiveX Automation in VEE, Making Automation Objects Available in VEE, Creating an Automation Object in a Program, Using Distributed Component Object Model (DCOM), Getting an Existing Automation Object, Manipulating Automation Objects, Data Type Compatibility, Deleting Automation Objects, Handling Automation Object Events


Creating an Automation Object in a Program

To control a server application from VEE, you need to create an automation object in your program. The CreateObject function lets you do that. To put the function in your program, click the fx toolbar button to get the Function & Object Browser and then select:

Built-in Functions=> ActiveX Automation=>CreateObject

Click Create Formula and place the Formula object in your program. The Formula contains the expression

CreateObject(ProgID)

which you need to modify to perform the desired action.

Note

ProgID is a human-readable string that identifies the Automation object that you want to create. To determine the ProgID for an automation object, refer to the vendor’s documentation.

Most of the time you want a new instance of an automation object created in a new instance of the server application. For example, the following VEE expression starts a new instance of Excel (even if Excel is already running) and returns a reference to a new "Workbook" object tied to the excel variable.

SET excel = CreateObject("Excel.Sheet")

See Also

Using ActiveX Automation in VEE, Making Automation Objects Available in VEE, Declaring Automation Object Variables, Using Distributed Component Object Model (DCOM), Getting an Existing Automation Object, Manipulating Automation Objects, Data Type Compatibility, Deleting Automation Objects, Handling Automation Object Events


Using Distributed Component Object Model (DCOM)

DCOM allows the Automation client (VEE) to control the Automation server (Excel, Access, etc.) remotely. You can run VEE on one computer and control Excel, for example, running on another computer. The second computer does not need VEE installed, just the application VEE is controlling.

To do this, the CreateObject function takes an optional second parameter that specifies the name of a remote host computer (server) on which to instantiate the object. (This functionality requires that DCOM be installed on both the client and server computers and that the proper security settings have been configured using dcomcnfg.exe.) With this additional parameter, the definition of CreateObject() looks like the following:

CreateObject ("ProgID", ["hostName"])

where hostName has to be of type Text. hostName can be specified as either a valid UNC or DNS domain name. Valid hostName specifications are shown below:

Set obj = CreateObject ("ProgID", "server")

Set obj = CreateObject ("ProgID", "\\\\server")

Set obj = CreateObject ("ProgID", "server.domain.com")

Set obj = CreateObject ("ProgID", "135.5.33.19")

VEE does not provide any programmatic control over the security settings used to instantiate objects on remote computers. This can be accomplished statically via the dcomcnfg.exe program.

See Also

Using ActiveX Automation in VEE, Making Automation Objects Available in VEE, Declaring Automation Object Variables, Creating an Automation Object in a Program, Getting an Existing Automation Object, Manipulating Automation Objects, Data Type Compatibility, Deleting Automation Objects, Handling Automation Object Events


Getting an Existing Automation Object

If you already created an automation object, you can get an active object or load an existing object from a file by using the GetObject function. To put the function in your program, click the fx toolbar button to get the Function & Object Browser, then select:

Built-in Functions => ActiveX Automation => GetObject

Click Create Formula and place the Formula object in your program. The Formula contains the expression

GetObject("fileName", "ProgID")

which you need to modify to perform the desired action.

The following expression gets an active object and returns a reference to a currently running Excel application's Application object. This call will fail if Excel is not running.

SET excel = GetObject("","Excel.Application")

The following expressions load an existing object from file. The ProgID parameter is optional:

SET excel = GetObject("d:/tmp/TestData.xls","Excel.Sheet")

or

SET excel = GetObject("d:/tmp/TestData.xls")

They return a reference to the sheet object associated with d:\tmp\TestData.xls in the currently running Excel application. If Excel is not already running, it will be started before loading the object. If ProgID is omitted, VEE uses the Component Object Model (COM) library to determine what application the file is associated with.

See Also

Using ActiveX Automation in VEE, Making Automation Objects Available in VEE, Declaring Automation Object Variables, Creating an Automation Object in a Program, Using Distributed Component Object Model (DCOM), Manipulating Automation Objects, Data Type Compatibility, Deleting Automation Objects, Handling Automation Object Events


Manipulating Automation Objects

After creating an automation object, you can manipulate the object to control server applications. Manipulating automation objects involves three basic operations: getting properties, setting properties, and calling methods. This section demonstrates these using previously initialized object variables named cell, sheet, and excel. The VEE keywords SET and ByRef are introduced.

Getting and Setting Properties

The expressions in this section are examples of getting and setting a property of an object. The following expression gets a property, where the value property returns the contents of the cell:

contents = cell.value

In the next expression, the value property returns the contents of the cell:

contents = sheet.cells(1,1).value

The next expression does the same property-getting action as the previous expression by implying the .value property because of default properties (explained below):

contents = sheet.cells(1,1)

Sometimes you want the contents, value and default property of the right-hand side (which happens by default) and sometimes you want a pointer to the object on the right-hand side, not its value. To get the object pointer you need to use SET to tell VEE not to get the default value. The next expression sets an object reference, where the cell variable is set to reference one cell out of the "collection" of cells:

SET cell = sheet.cells(1,1)

The difference between this example and the second example is that SET specifies that the left-hand-side wants the right-hand-side object itself, not its default property.

The following expressions are examples of setting a property of an object. The following three expressions are identical because of default properties:

cell.value = "Test Data2:"

sheet.cells(1,1).value = "Test Data2"

sheet.cells(1,1) = "Test Data2"

About Default Properties

Most automation objects support the concept of a default property or method. You can use this concept when manipulating automation objects as shown in the previous examples. In the case of cell, its default property is value. So, the first example above in getting a property could use this concept to imply the .value property and be entered as

contents = cell

This means that the expression

contents = sheet.cells(1,1)

would not only return a cell from the collection of cells, but it would also evaluate the default property (.value) on that cell as in the expression

contents = sheet.cells(1,1).value

To get a cell itself from the collection of cells, you must use the keyword SET in the expression such as

SET cell = sheet.cells(1,1)

This sets cell to be a pointer to that cell in Excel. Compare this to the expression

contents = sheet.cells(1,1)

(mentioned above) where contents gets the contents of that cell in Excel. Also, the .value property is implied on Set Property, such that the following two expressions perform the identical function:

cell.value = "Test Data”

cell = "Test Data"

Calling Methods

Calling a method is similar to getting a property, but methods have parenthesis-like () functions and can take parameters. Properties are generally used to get or set the value of an attribute of the object. Methods are generally used to perform an action.

The following expression is an example of calling a method on an object:

result = excel.CheckSpelling("aardvark")

By default, parameters are passed by value. For example, cells(1,1) actually calls a method and passes two parameters (1 and 1). Passing by value simply sends the parameter values to Excel and a return value comes back. The parameter values are unchanged.

Some automation methods have parameters that are passed by reference. The parameter’s value is changed by the automation server and a new value for the parameter is passed back to VEE. For example, an ActiveX instrument control might contain an automation method called by this expression

passed = Scanner.GetReading (ByRef Reading)

where the method’s return value for passed is true if the getReading worked or false if it did not, and any other values are returned in the ByRef parameter Reading. You should initialize the variable Reading before passing it to the function and have an output terminal on the Formula object containing the expression so you can use any returned values.

The ByRef keyword is supported in VEE, and the Function & Object Browser displays in its information area the parameters passed using ByRef. ByRef does not support all data types. See Table “Converting from VEE Data Types to Automation Scalar Data Types”.

Using Enumerations

Type libraries can provide enumerations that appear in the Class area of VEE’s Function & Object Browser. Enumerations make using object methods and properties easier. For instance, the Window object in Excel has a WindowState property. The WindowState property is of type XlWindowState enumeration. There are three values for this enumeration:

xlMaximized (-4137)

xlMinimized (-4140)

xlNormal (-4143)

VEE supports enumerations, which allows you to use the following expression when using object methods and properties:

Window.WindowState = xlMinimzed

Using the ActiveX Object Browser

The ActiveX Object Browser is part of the Function & Object Browser that opens when you press fx on the toolbar. The browser configuration changes when you select ActiveX Objects. The browser lets you explore the properties, methods, and events that an ActiveX object provides. ActiveX information appears here only if you selected automation or control type libraries (Device [image] ActiveX Automation References or ActiveX Control References). A Function & Object Browser with ActiveX information for the Access type library.

When a Library name is selected, the Class area displays dispatch interfaces (dispinterfaces) and enumerations that are available. For a selected dispinterface, the available properties, methods, and events appear in the Member area. For enumerations, the constants are listed. The figure above displays some of the functionality available for the Access library. The selected ComboBox dispinterface contains properties, a method, and many events that are listed in the Member area. The figure following shows the relationship between entries in the browser’s Classes and Members areas, including their identifying icons:

The browser’s information area (just above the buttons) displays a help string associated with the property, method, event, or constant if this information is provided by the automation object. This syntax contains the object’s type information in the parameter list. Parameters surrounded by square brackets [ ] are designated as optional. Some applications may not provide these short help strings.

Type information is provided for an ActiveX object’s properties, method parameters, and return type. If no parameter type is specified, the default type is VT_VARIANT. In most cases, VEE automatically handles type conversion for VT_VARIANT. See This table and following for more information about Automation data type and VEE data Type conversion.

For a property, the browser displays type information about the property, such as whether it is a read-only or write-only property and whether it is the default property. You can create a Formula object to perform a get or set of that property. The following is an example of what the browser displays in the information area for a property:

DEFAULT PROPERTY Name as Text

For a method, the browser displays type information about each parameter in the parameter list and the return value. Methods can also be the default member, so the browser also indicates this. You can create a Formula object for a method that is configured to call that method. The following is an example of what the browser displays in the information area for a method:

METHOD Void SetData(vValue, vFormat)

For events, the browser displays the same type information as for a method. However, the event handler associated with an event is usually called by the client application. In the case of controlling Access by automation, Access calls the event handler UserFunction. In the case of using an ActiveX control, the ActiveX control calls the event handler UserFunction.

Since your program or VEE does not call these callback event handlers, the Create Formula button is grayed out. You can only view information about an event. The Function & Object Browser does not let you create event-handler UserFunctions because events must be tied to a particular ActiveX automation variable or an ActiveX control.

To create an event handler, go to the object menu of the appropriate Declare Variable or ActiveX control. The following is an example of what the browser displays in the information area for an event:

EVENT Void Click()

For constants in an enumeration, the browser displays the value of the constant. The following is an example of what the browser displays in the information area for a constant:

CONSTANT tvwRootLines = 1

For constant values less than 0 and greater than 1024, VEE also displays the hexadecimal value of the constant. This information appears as:

CONSTANT xlNormal = -4143 (#HFFFFEFD1)

Clicking the Help button opens the help file and topic associated with the selected ActiveX object member if that information is provided by the object. If no information is available, a dialog box appears, indicating that no help is available for the selected member. This help information is provided by the application vendor and is not part of VEE Online Help.

See Also

Using ActiveX Automation in VEE, Making Automation Objects Available in VEE, Declaring Automation Object Variables, Creating an Automation Object in a Program, Using Distributed Component Object Model (DCOM), Getting an Existing Automation Object, Data Type Compatibility, Deleting Automation Objects, Handling Automation Object Events


Data Type Compatibility

ActiveX automation provides support for certain data types. This section describes the type conversion that takes place between VEE data types and ActiveX automation data types. Type conversion occurs automatically.

Table 1 indicates the automation data types that are supported and the corresponding VEE Data Types in VEE 8.5 Execution Mode.

Table 1 Converting from Automation Scalar Data Types to VEE Data Types in VEE 8.5 Execution Mode

Convert from Automation Data Type | Convert to VEE Data Type | Notes
VT_EMPTY | Text | Text with empty string ("") is returned. Use isVariantEmpty() to determine if variant was of type VT_EMPTY
VT_NULL | Text | Text with empty string ("") is returned. Use isVariantNull() to determine if variant was of type VT_NULL
VT_UI1 | UInt8 |
VT_UI2 | UInt16 |
VT_I2 | Int16 |
VT_I4 | Int32 |
VT_I8 | Int64 |
VT_R4 | Real32 |
VT_R8 | Real64 |
VT_CY | Real64 | 8-byte fixed point integer with 4 digits to right of decimal is converted to VEE Real64. Use isVariantCurrency() to determine if variant was of type VT_CY.
VT_DATE | Real64 | Days since 12/30/1899 converted to VEE’s representation of date/time in seconds since Jan 1, 0001.
VT_BSTR | Text |
VT_DISPATCH | Object |
VT_ERROR | Int32 | An Int32 with value of the scode is returned. Use isVariantError() to determine if variant was of type VT_ERROR.
VT_BOOL | Boolean |
VT_VARIANT | * | Only valid in ByRef case (VT_VARIANT | BYREF) In this case, the variant points to another variant. VEE creates a container based on the embedded variant’s type.
VT_UNKNOWN | Object |

Table 2 indicates the VEE 8.5 Execution Mode data types supported and the corresponding automation data types. Unlike the inverse mappings shown in the previous table, these are not fixed one-to-one mappings. Most automation server objects are capable of coercing data to the required data type.

For example, if the target property is a long integer, such as the X coordinate of a point, you can pass not only an Int32 which is the exact match, but also a real or even a text string, as long as it is a string of digits. However, in case of an array, which is always passed as a VARIANT, acceptable data type and array shape depends on the implementation of the target COM object.

Table 2 Converting from VEE Data Types to Automation Scalar Data Types in VEE 8.5 Execution Mode

Convert from VEE Data Type | Convert to Automation Data Type | Notes
UInt8 | VT_UI1 |
UInt16 | VT_UI2 |
Int16 | VT_I2 |
Int32 | VT_I4 |
Int64 | VT_I8 |
Real32 | VT_R4 |
Real64 | VT_R8 |
Text | VT_BSTR |
Boolean | VT_BOOL | Use asVariantBool() on any scalar VEE data type that can be cast to an Int16, (UInt8, Int16, Int32, Real32, Real64, Text).
<scalar of type *> | VT_CY | Use asVariantCurrency() on any scalar VEE data type that can be cast to a Real64 (UInt8, Int16, Int32, Real32, Real64, Text).
<scalar of type *> | VT_DATE | Use asVariantDate() on any scalar VEE data type that can be cast to a Real64 (UInt8, Int16, Int32, Real32, Real64, Text).
<scalar of type *> | VT_ERROR | Use asVariantError() on any VEE data type that can be cast to an Int32 (UInt8, Int16, Int32, Real32, Real64, Text). Value of Int32 is assigned as the scode (error number) for the error.
Variant | <scalar of variant type *> | The current type of the VEE container is converted to the appropriate variant type. For instance, if the Variant container holds a VEE Int32, VEE will create a variant of type VT_I4.
Object | VT_DISPATCH | If VEE holds an IDispatch pointer to the object.
Object | VT_UNKNOWN | If VEE has an IUnknown pointer but not an IDispatch pointer.

Table 3 shows array conversions from Automation data type to VEE 8.5 Execution Mode data type.

Table 3 Converting from Automation Array Data Types to VEE Data Types in VEE 8.5 Execution Mode

Convert from Automation Data Type | Convert to VEE Data Type | Notes
VT_UI1 | UInt8 Array |
VT_UI2 | UInt16 Array |
VT_I2 | Int16 Array |
VT_I4 | Int32 Array |
VT_I8 | Int64 Array |
VT_R4 | Real32 Array |
VT_R8 | Real64 Array |
VT_BSTR | Text Array |
VT_BOOL | Boolean Array | Use isVariantBool() to determine if variant array was of type VT_BOOL.
VT_CY | Real64 Array | 8-byte fixed point integer with 4 digits to right of decimal is converted to VEE Real64. Use isVariantCurrency() to determine if variant array was of type VT_CY.
VT_DATE | Real64 Array | Days since 12/30/1899 converted to VEE’s representation of date/time in seconds since Jan. 1, 0001. Use isVariantDate() to determine if variant is of type VT_DATE.
VT_ERROR | Int32 Array | An Int32 with value of the scode is returned. Use isVariantError() to determine if variant array was of type VT_ERROR.
VT_VARIANT | <array of homogeneous type OR a record> | If the array elements are all of the same fundamental data type, VEE creates an array of the type indicated by the scalar mapping in Table 1. A VEE record is created for a variant containing a mixed data type array.
VT_DISPATCH | N/A | Arrays of type Object not supported.
VT_UNKNOWN | N/A | Arrays of type Object not supported.

Table 4 shows Automation Data Type modifiers.

Table 4 Automation Data Type Modifiers

Automation Type Modifiers | VEE Type | Notes:
VT_BYREF | Either scalar or array of the type indicated by the scalar mapping table above. | For instance, VT_BYREF | VT_BSTR would generate a VEE Text container. In the case of a scalar VT_VARIANT, the variant points to another variant. VEE creates a container based on the data type of the embedded variant.

See Also

Using ActiveX Automation in VEE, Making Automation Objects Available in VEE, Declaring Automation Object Variables, Creating an Automation Object in a Program, Using Distributed Component Object Model (DCOM), Getting an Existing Automation Object, Manipulating Automation Objects, Deleting Automation Objects, Handling Automation Object Events


Deleting Automation Objects

Automation objects are responsible for deleting themselves when VEE releases its reference to them. When VEE no longer holds a reference to an automation object, it tells the object that the reference has been released. The object then deletes itself unless other ActiveX automation controller applications are still using it. VEE releases references to automation objects in the following cases:

• The Delete Variable object is executed on the automation object’s variable name. However, VEE may also have other pointers to these Automation objects. See Delete Variable for more information.

• Delete Variables at Prerun is enabled in Default Preferences and you restart the program.

• VEE exits, or the commands File [image] New or File [image] Open are used.

See Also

Using ActiveX Automation in VEE, Making Automation Objects Available in VEE, Declaring Automation Object Variables, Creating an Automation Object in a Program, Using Distributed Component Object Model (DCOM), Getting an Existing Automation Object, Manipulating Automation Objects, Data Type Compatibility, Handling Automation Object Events


Handling Automation Object Events

Automation objects can generate events. VEE, as an automation controller, lets you catch events via UserFunctions. You can create event-handler UserFunctions for an automation object that generates events if you have declared a variable of the specific type and have enabled its events. You can create an event-handler UserFunction for each event an object can generate.

You can create an event-handler UserFunction when you declare a variable for the object and enable its events (if they are available).

1 After declaring the variable and specifying its type, including enabling events, open the Declare Variable object menu.

In the object menu, click Create Event Handler… The Create Event Handler UserFunction browser appears. See the following figure.

The Member area lists all of the events available for the dispatch interface listed in the Class area.

2 Click an event name to select it.

When you select an event, the browser information area presents event details and the status area shows the UserFunction title VEE will create. Press the Help button to get information about using the event. Not all events have online help as the library vendor is responsible for providing it. Online help for events is not part of VEE Online Help.

3 Click Create Handler. The new UserFunction window appears. If you open this dialog box again to create another event handler, you will notice the icons change color next to events with existing handlers.

Each new event-handler UserFunction is empty except for any required inputs or outputs. You must program it to handle the event appropriately. To edit an existing event, in the Declare Variable object menu, click Edit Event Handler...

Events are tied to the declared variable’s name. The UserFunction title combines the variable name with the event name. For example, if you declared a variable named combo and specified its type as Access.ComboBox you could create event-handler UserFunctions with names such as:

combo_AfterUpdate

combo_Change

combo_DblClick

combo_KeyDown

Events are callback functions. You must program the generated UserFunctions (the callback functions) to handle each event appropriately. If the automation object generates an event, it calls the related UserFunction to handle the event. Automation objects sometimes expect a return value from VEE when they fire an event. If so, you must program the UserFunction to return a value.

When the object expects a return value, it waits until VEE provides this return value. You should write an event-handler UserFunction to work quickly, since both VEE and the automation server, such as Access, wait until the event-handler UserFunction returns.

Since the automation server waits until the event-handler UserFunction returns, the UserFunction is executed in non-timeslicing mode. That is, the UserFunction runs to completion without timeslicing with the rest of the VEE program. Because it is not timeslicing, breakpoints do not work in an event-handler UserFunction. Also, errors do not stop VEE. Errors are turned into Cautions and execution continues.

See Also

Using ActiveX Automation in VEE, Making Automation Objects Available in VEE, Declaring Automation Object Variables, Creating an Automation Object in a Program, Using Distributed Component Object Model (DCOM), Getting an Existing Automation Object, Manipulating Automation Objects, Data Type Compatibility, Deleting Automation Objects


Perform Math on Arrays Whenever Possible

Performing mathematical operations on arrays greatly improves program performance. For example, suppose a test must find the square root of measurements being taken. The traditional way to program this would be to take a measurement and calculate the square root in a loop. Instead, in VEE, you can store all the measurements in an array and calculate the square root of the array in one step.

There are two programs. The first program iterates 1024 times. Each iteration calculates a square root.

The second program creates an array of 1024 elements and calculates the square root of the array (yielding an array of square roots).

Although the two programs both yield the same results, the second program executes about 6 times faster than the first one. (This example uses a 300 MHz Pavilion PC.)

The difference in the execution speeds of the two programs is due to the time required for an object to execute. There is a fixed amount of overhead when an object executes. Therefore, when you reduce the number of times an object executes by using arrays rather than scalar values, the program runs faster.

Using the Do object is a good idea when timing to make sure the timer triggers first in both programs. The ramp function generates an array with 1024 elements starting at 0 and ending at 1023.

note

To ensure faster execution, always make sure you are using the most recent execution mode in VEE. To do this, click File [image] Default Preferences (or use the button on the tool bar). Select VEE6 under Execution Mode and click Save. In the status bar at the bottom of the VEE window, you should see VEE6 listed.

See Also

Perform Math on Arrays Whenever Possible

Make Objects into Icons Whenever Possible

Reduce the Number of Objects in Programs

Other Ways to Optimize Agilent VEE Programs

Keys To Faster Programs


Make Objects into Icons Whenever Possible

The more information VEE has to maintain on the screen, the more time it will take the program to run. To optimize the program, use iconic views for objects that update their contents, such as the Counter, instead of using open views. The following example operates about 46 times faster using an iconic view for the For Count and Counter object.

See Also

Perform Math on Arrays Whenever Possible

Reduce the Number of Objects in Programs

Other Ways to Optimize Agilent VEE Programs

Keys To Faster Programs


Reduce the Number of Objects in Programs

As you become more experienced, you will tend to use less objects in VEE programs. There are two more techniques to reduce the number of objects and therefore optimize programs:

1 Use a single equation in a Formula object instead of using separate mathematical objects. For example, put the equation ((a + b) * c)/d into a Formula object instead of using separate objects for addition, multiplication, and division. Also, use constants in the formula instead of constant objects connected to inputs. (Set constants with Set Variable.)

2 Nest function calls within other function parameter lists. For instance, in the first program, the function randomize uses the array generated by the function ramp. In the second program, the function call to ramp is nested in the call to randomize, resulting in slightly faster program execution.

See Also

Perform Math on Arrays Whenever Possible

Make Objects into Icons Whenever Possible

Other Ways to Optimize Agilent VEE Programs

Keys To Faster Programs


Other Ways to Optimize Agilent VEE Programs

There are other optimization techniques that you can use in programs when appropriate:

  • Make sure you are using the VEE compiler by running your programs in VEE 4 or higher Execution Mode. For more information, refer to Execution Mode.

  • Run the program from the panel view instead of the detailed view. VEE will have less objects to maintain on the screen.

  • Use global variables rather than pass values (especially large arrays or records) into and out of UserObjects and UserFunctions. Declare all the global variables. This also allows you to use local variables. See Data [image] Variable [image] Declare Variable.

  • Collect data for graphical displays and plot the entire array at once rather than plotting each individual scalar point. If the X values of a plot are regularly spaced, use an XY Trace display rather than an X vs. Y Plot.

  • Use one If/Then/Else object with multiple conditions instead of multiple If/Then/Else objects.

  • Set graphical displays to be as plain as possible. The settings that allow the fastest update times are Grid Type [image] None and nothing checked in the Properties dialog box. Only use AutoScale control pins where necessary, and turn off the Automatic AutoScaling if not needed (in the Scales folder).

  • When reading data from a file, use the ARRAY 1D TO END: (*) transaction instead of performing READ transactions on one element at a time and using the EOF pin.

  • Use the Sequencer to control the flow of execution of several UserFunctions instead of separate Call objects.

  • When using the Sequencer, only enable logging for transactions where the Log record is required.

  • When using Strip Charts and Logging AlphaNumeric displays, set the Buffer Size in Properties to the smallest number possible for your application.

  • Use the triadic operator, (condition ? expression1 : expression2), instead of the If/Then/Else object with Gates and a Junction.

  • When using bitmaps, set them to Actual or Centered rather than Scaled, since Scaled will take a few moments longer.

  • When using indicators such as the Fill Bar or Thermometer, turn off Show Digital Display.

  • When using Color Alarms, if you are switching between colors rapidly, turn off Show 3D Border.

In addition to the techniques already mentioned, linking compiled functions in other languages to your VEE programs can increase execution speed. Using compiled functions on PCs (as DLLs) are described in the next section.

See Also

Compiled Functions, Using DLL, Perform Math on Arrays Whenever Possible, Make Objects into Icons Whenever Possible, Reduce the Number of Objects in Programs, Keys To Faster Programs


Keys To Faster Programs

This section gives some guidelines to help improve VEE program performance.

note

If you developed programs on a version of VEE prior to VEE 6.0, see “Using VEE Execution Modes” for information on converting your program to use the compiler.

The following constructs will help you get the most speed benefit from the compiler (when the Execution Mode is set to VEE 4, VEE 5 or VEE 6 in File [image] Default Preferences):

• Use the Profiler

You can use the Profiler (located at View [image] Profiler) to categorize which routines are taking more time than you want them to. To run the Profiler:

1 Click Start Profiling and then run your program.

2 When you have finished running your program, click Refresh to see the results.

3 Click Stop Profiling to stop the profiler. Click Clear to clear the current results displayed.

• Look at line colors

Lines are colored when VEE can determine the data type before execution. The more colored (non-black) lines, the faster the program will run.

• Add Terminal Constraints

Because UserFunctions can be called from multiple places, VEE cannot determine the input data types before the program runs. To speed up UserFunctions, whenever possible add terminal constraints on their data input terminals.

• Use Declared Variables

If you use global variables, use Declare Variable (located on the Data menu) when possible to declare the type and shape of your variables so VEE can infer types for them prior to execution. This technique also allows you to set the scope of your variables.

• Eliminate the Autoscale control input

A common programming practice is executing the Autoscale control input on graphical displays more often than necessary. If you can wait to execute Autoscale until after the display has finished updating, instead of after each point is plotted, your program will execute faster. You can eliminate the Autoscale control input by using the Automatic Scaling property (see the Scales tab) which can further improve execution speed.

• Send a complete set of data

On graphical displays, when the Automatic Scaling property is turned on (see the Scales tab), the program executes faster if a complete set of data is sent to the display. Then the display automatically rescales once. If a program sends one data point at a time to the display, the display may automatically rescale after each data point which will slow down program execution. In this case, use a Collector object to create an array and then send the array to the display.

• Execute the display only once

If a display is showing the final output of a loop, but not tracking data generated for each iteration of the loop (for example, an AlphaNumeric object not a Logging AlphaNumeric), do not have it execute every time in the loop. Connect the iterator's sequence output pin to the display's sequence input pin so the display only executes the last time.

• Turn debugging features off

Once you know the program is running correctly, run the program with debugging features off. Use File [image] Default Preferences and select Disable Debug Features in the Debug group.

You can also use the -r option, or run VEE RunTime. Because no debug instructions are generated in those modes, your program will run a little faster. However, you will not be able to perform any debugging actions such as, pausing, stepping, Breakpoints, Line Probe, Show Data Flow and Show Execution Flow.

See Also

Perform Math on Arrays Whenever Possible

Make Objects into Icons Whenever Possible

Reduce the Number of Objects in Programs

Other Ways to Optimize Agilent VEE Programs


Troubleshooting Techniques

This section describes instrument control troubleshooting and common situations and possible recovery actions. The following table addresses instrument control troubleshooting.

Problem

Remedy/Cause

Instruments do not respond at all.

The following conditions must be met:

  • Instruments must be powered up and connected to the interface by a functioning cable. The appropriate I/O libraries must be installed.

  • For To/From VXIplug&play objects: You must have installed and configured the appropriate VXIplug&play driver files for your instrument. Also, the correct VXIplug&play address string must be specified in the Advanced Instrument Properties dialog box for each instrument. The address for each instrument must be unique.

  • For Direct I/O, Panel Driver, and Component Driver objects: The interface logical unit and instrument addresses must match settings in the Address field of the Instrument Properties dialog box. The address for each instrument must be unique. Also, the Live Mode field in the Advanced Instrument Properties dialog box must be set to ON.

  • You or your system administrator must properly configure VEE to work with instruments. Normally this is done during VEE installation. See the installation guide.

You cannot determine the instrument address.

For GPIO and serial interfaces, the instrument address is the same as the interface logical unit. GPIB instrument addresses are set by hardware switches or front panel commands. See the instrument's programming manual for details. VXI devices have logical addresses set by switches on the outside of the cards (usually the cards must be removed from the card cage to access the switches). See Help => Contents and Index => Tell Me About .. => Configuring Instruments for further information about configuring addresses.

You cannot determine the interface logical unit.

The interface logical units must be configured with the I/O Config utility supplied with the Agilent I/O libraries. See Installing the Agilent I/O Libraries for further information. See the table Recommended I/O Logical Units for recommended logical unit settings.

This table addresses general VEE troubleshooting.

Problem | Possible Cause | Suggested Solutions
When running a program created in versions prior to VEE 6.0 in VEE 6 Execution Mode, the program does not operate as expected |  | See Help => Connects and Index => Tell Me About .. => Execution Mode for possible solutions.
Your UserObject does not operate as expected. | You might be crossing the context boundaries with asynchronous data (such as connecting to an XEQ pin on an object inside the UserObject). | Possible Solution 1: Move any asynchronous dependencies to outside the UserObject. Possible Solution 2: Enable Show Execution Flow or Show Data Flow to view the order of operation in your program.
You want to change the functionality of an object. |  | Use the object menu which includes features that let you add a control input terminal and edit properties.
You only get one value output from an iterator within a UserObject. | A UserObject only activates its outputs once. | Take the iterator out of the UserObject.
An iterator only operates once. | Your iteration subthread is connected to the sequence output pin, not the data output pin. | Start the iteration subthread from the data output pin.
For Count does not operate. | The value of For Count is 0 or negative. | Change the value. If you need a negative value, negate the output or use For Range.
For Range or For Log Range does not operate. | The sign of the step size is wrong. If From is less than Thru, Step must be positive. If Thru is less than From, Step must be negative. | Change Step.
VEE appears to hang -- the pointer is an hourglass. | Possible Cause 1:VEE is rerouting lines because you have Auto Line Routing set on and you moved an object. Possible Cause 2: VEE is printing the screen or the program. Possible Cause 3: You just Cut a large object or a large number of objects. VEE is saving the objects to the Paste buffer. | Wait. If the pointer does not change back to the crosshairs within a few minutes, type CTRL+C (or what your intr setting is in the terminal window from which you started VEE 6.0), close the VEE window, or kill the VEE process.
You cannot Open a program, Cut objects, or delete a line (the feature is grayed). | The program is still running. | Press Stop to stop the program, then try the action again.
You cannot Paste (the feature is grayed). | The Paste buffer is empty. | Cut, Copy, or Clone the object(s) again.
You cannot Cut, Create UserObject, or Add to Panel (the feature is grayed). | No objects are selected. | Select the objects and try the action again.
A UserObject only outputs the last data element generated. | UserObjects do not accumulate data in the output terminal buffer. The buffer only holds the last data element received. | Use a Collector to gather all of the data generated into an array. Send this data to the output terminal.
You cannot get out of line drawing mode. |  | Double-click or press Esc to end line drawing mode.
You get a Parse Error object when you Open a program. |  | Replace the Parse Error object with a new object.
Your characters are not appearing correctly. | You have a non-USASCII keyboard. | See Configuring VEE for recovery information.
Your colors outside of VEE are changing (although when you are in VEE , the VEE colors look normal). | Your color map planes are all used. | See Configuring VEE for recovery information.


The Agilent VEE Profiler

The Profiler helps you optimize programs by displaying the execution speeds of UserFunctions or UserObjects in the program.

You can use the Profiler to identify the slow points in a program and apply the techniques described here to increase the program speed. The examples\Applications\mfgtest.vee program is shown below.

To turn on the Profiler, select View [image] Profiler. Then run the program. The Profiler lists comparative information regarding the amount of time it takes to execute each UserObject and each UserFunction.

See Also

To Profile Execution Parameters

Profiler


Programmatic Properties

The following properties are programmatically accessible for VEE objects.

Property | Object
BackColor, ForeColor, Title, Size, Location, and Visibility | All VEE objects
Value | Toggle Controls, Constants, Continuous Controls
EnumValue, EnumValues, EnumIndex | Selection controls
EnableOnPing | Confirm (OK) Objects
EnableEditing | VEE Data Objects with "Enable/Disable Editing" control input pin
PopupPanelTitle | Main, UserFunctions, and UserObjects
Size and Location | PopupPanel for Main or UserFunctions
Tab index | VEE Objects in panel view
BackColor | UserFunction/UserObject panel view and Main panel view

note

Property name is not case sensitive. Only run-time properties can be GET/SET programmatically. Design-time properties do not change. A value set in the Property window is called design-time value.

When a program is not running, VEE will display an object in workspace using the design-time value. For example, you set the backcolor of a Label to Red in the property window, then in a formula object, you set the backcolor of that Label to Green. Here although the Label's backcolor is changed to Green programmatically, the design-time value of the Label's backcolor is still Red. So the Label will have Red backcolor before the program runs or after the program finishes running. The Label may have Green backcolor only when the program is running. This also applies to Markers of XY trace, X vs Y Plot, Strip Chart, and other display objects. Markers will go back to the default position after program stops.

Yon can GET/SET properties of objects in a Secured UserFunction or in an Imported UserFunction, even from Main.

More Notes for Markers

To programmatically set a marker's position of a graphical (XY) display object, you will need a Formula box to set the new value to the marker.

To move the marker to your desired spot on a trace, you need to make sure that the Formula box runs after that XY display object. If the formula box runs before the XY display object, the marker will go to wherever you set since there is no trace on the XY display object until that XY display object runs. Moreover, the marker will stay at the position that you set even after the XY display runs.

Location

Device [image] Function & Object Browser [image] VEE Objects

See Also

To Change Properties Programmatically, To Change Object's Name and Scope


Compiler Warning

Uncertain Data Flow Compiler Warnings

Agilent VEE can detect the Uncertain Data Flow Compiler Warnings and display these warnings in the Output window. This warning is related to the VEE compiler and can confuse the execution order. It is difficult for users to figure out how to avoid this warning. This topic gives you some clues on what this warning is, how it is caused, and how to avoid it.

What is the Uncertain Data Flow Compiler Warning

VEE logs this Uncertain Data Flow Compiler Warning when VEE detects potential risks that may confuse the execution order and cause some objects never to execute.

In the following VEE program. Object 3, 4 and 5 are downstream objects of Object 1 and 2. Object 6 should execute after Object 3, 4, and 5. The correct execution order should be 1-2-3-4-5-6 or 2-1-3-4-5-6.

However, the actual execution order is 1-2-3-4-6-5 or 2-1-3-4-5-6 depending on the execution order of Object 1 and 2. The second execution order is correct, but the first one is incorrect. In the first one, the Object 6 executes prior to Object 5. It is even worse, if the Object 6 is an object that can terminate the execution of your VEE program, like Stop, Raise Error, etc, the Object 5 will never execute.

Overall, when a sequence output pin has the potential risk to propagate before any downstream object, VEE logs a compiler warning in the Output window. That is the Uncertain Data Flow Compiler Warning.

The Reason of the Uncertain Data Flow Compiler Warning

In general, the flow of execution through your VEE program is determined by data flow, that is the flow of data from object to object within a VEE program. In some cases, sequence pins are used to specify the order of execution. Sequence pins include sequence input pins and sequence output pins.

A sequence output pin of an object propagates after all the data output pins of that object have activated and data flow has propagated as far as possible. Here, "propagate as far as possible" does not mean all downstream objects have executed. Sometimes, a sequence output pin is activated even when some downstream objects have not executed yet, which may disturb the execution order and cause the compiler warning.

For instance, in the above program, if the Object 1 executes prior to Object 2, then when the sequence input pin of Object 3 is activated, its data input pin is still not activated. Thus, data flow of the Object 2's data output pin cannot propagate further. And, Object 1 has only one data output pin, so VEE fires Object 1's sequence output pin by putting Object 6 into a queue. After that, Object 2 executes, then Object 3 executes followed by Object 4. After the execution of Object 4, VEE will put Object 5 into the same queue that Object 6 in.

Objects in the queue start to execute since there is no object without constrains to execute in the current thread. Object 6 executes prior to Object 5 because the queue is a FIFO (First In First Out) queue.

Therefore, the direct reason why Object 6 executes prior to Object 5 is Object 6 is fired before Object 5. The root cause is VEE compiler may propagate one object sequence output pin even when some downstream objects have not executed. To help you understand, see a more complicate program below.

In this program, Object 4, 5, and 6 are downstream objects of Object 1, 2, and 3, so Object 4, 5, and 6 should execute before Object 7, 8, and 9. Actually, Object 6 executes only before one of Object 7, 8, and 9. In other words, two of Object 7, 8, and 9 execute before Object 6. The execution order of Object 1, 2, and 3 determines which two objects execute first. For example, if the execution order of Object 1, 2, and 3 is 1-2-3, then the execution order of the above program is 1-2-3-4-5-7-8-6-9. If the execution order of Object 1, 2, and 3 is 3-2-1, then the execution order of the above program is 3-2-1-4-5-9-8-6-7. So, this program will cause the Uncertain Data Flow Compile Warning too.

How to Avoid the Uncertain Data Flow Compiler Warning

According to the analysis above, the Uncertain Data Flow Compiler Warning is directly related to sequence output pins. So, It is best to use sequence pins as less as possible. See Understanding Sequence Pins for recommended use of sequence pins and common cases of over-using sequence pins. The following tips also can give you some clues on how to avoid the Uncertain Data Flow Compiler Warning.

Wiring to the device that has no input pin as far as possible

The above VEE program will cause the Uncertain Data Flow Compiler Warning. The AlphaNumeric object and the Exit Thread object will never execute if the Text object executes after the If/Then/Else object. To avoid this, use the following programming style -- Wiring to the device that has no input pin as far as possible.

Making the downstream thread only one branch as far as possible

In the following program, there are two parallel threads (one thread is in orange, one is in green) connected together, which will cause the Uncertain Data Flow Compiler Warning. Raise Error may executes without the execution of objects in the blue rectangle (Text, Formula 5, Formula 6, and Exit Thread) if the If/Then/Else object executes before the Formula 1 object.

To avoid the problem, use a serial flow instead of a parallel flow in the downstream thread of the If/Then/Else object like following program. In this program, the two parallel threads are put into a UserFunction.

It is difficult for users to avoid this kind of compiler warning completely, so it is wise to let VEE detect this compiler warning automatically and log it into the Output window. It is much easier for users to analyze the compiler warning and improve the corresponding VEE program once VEE has detected the warning . By default, VEE detects the Uncertain Data Flow Compiler Warning automatically during compiler time. To disable this feature, go to File => Default Preferences, under the General tab, uncheck the Uncertain Data Flow Compiler Warning.

NOTE

Please note that VEE only detects and logs the Uncertain Data Flow Compiler Warning during compiler time, which means that VEE will not detect such compiler warning and log it in the Output window if you run the same program for two or more times. To let VEE detect and log the compiler warning for a VEE program, reload and run the VEE program.

See Also

Understanding Propagation, Pins and Propagation.


ActiveX Controls

VEE does not support all ActiveX Controls. If a control is incompatible with VEE, an error will probably occur when you add the control to your program or while you are using it.

At the time VEE 8.0 was released, the following ActiveX Controls were known to not work well with VEE and should be avoided:

Microsoft Forms Object Library

Microsoft ADO Data Control 6.0

Adobe PDF 7.0 Viewer


Error 758

Failed to prepare for .NET operations.

Symptoms

You may receive Error 758 when the installer has failed to install all the required components. The two most common symptoms are:

1. When you select Device->.NET Assembly References dialog or Device->Windows Forms Control, you may receive this error dialog:

2. When you select I/O->Instrument Manager and click on the IVI-COM Driver button for an instrument, you may receive this caution dialog:

Cause

The above two symptoms are caused by the Primary Interop Assemblies (PIAs) for IVI shared components not being installed into the .NET Global Assembly Cache.

Fix

You need to find out where your .NET Framework SDK 2.0 installation directory is. It is usually located at <Program Files>\Microsoft Visual Studio 8\SDK\v2.0. You also need to find out where your IVI installation directory is. The default directory should be <Program Files>\IVI Foundation\IVI.

Open up a Command Prompt, change directory to your .NET Framework SDK 2.0 installation directory, and then run a batch file installed by IVI. For example, if your .NET Framework SDK 2.0 is installed at C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0, and your IVI installation directory is c:\program files\IVI Foundation\IVI, then the command line would look like:

cd C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin

“c:\Program Files\IVI Foundation\IVI\bin\Primary Interop Assemblies\IviPiaRegistration.bat” “c:\Program Files\IVI Foundation\IVI\bin\Primary Interop Assemblies”

If the above batch file was run successfully, you should see lines like “Assembly successfully added to the cache” displayed in your command prompt window. Restart VEE.

NOTE

You can not run the above batch file successfully if you don' t have Gacutil on your machine. Installing .NET Framework SDK will install Gacutil on your machine.

Refer to MSDN for more information.


Memory Leak in Transaction Objects

Under certain conditions, memory leaks occur when using transaction objects in your VEE program. Direct I/O and From File are examples of transaction objects.

The memory leak condition exists only if a transaction object contains two READ transactions that both reference the same output pin, but use different data types. The following pair of transactions is an example:

READ TEXT x STR
READ TEXT x REAL

Use one of the following workarounds to prevent the memory leaks:

If you do not need the value of x that results from the first transaction, you may reference a special symbol called null. Include the word null in the first READ transaction instead of using the data output pin name. The object reads the data and discards it, then executes the next READ transaction. The transaction object would contain:

READ TEXT null STR
READ TEXT x REAL

Add a second output pin to accommodate the two pieces of data and have each transaction reference a different data output pin. Such transactions might appear as:

READ TEXT x STR
READ TEXT y REAL


Memory Leak with Math Expressions

Memory Leak with Expressions that Error

Under certain very rare conditions, memory leaks may occur when using math expressions in Formula objects, or in transaction objects that accept math expressions.

Your program may leak memory when a Formula object uses an Error pin, and the Error pin fires during the expected course of program execution. An example of this condition is where an expression performs a divide-by-zero operation causing the Error pin to fire.

A similar condition exists in transaction objects that accept math expressions, and use Error pins. A To File object might contain the transaction

WRITE TEXT a/b EOL

Since math expressions are evaluated in transaction objects the same way as in Formula objects, the potential for memory leaks is the same.


Runtime Error 553

You may encounter a VEE Runtime error (Error Number 553) when running an Excel related VEE program.

This runtime error is caused by a Microsoft known issue.

For more information on this Microsoft known issue, refer to GetObject or GetActiveObject cannot find a running Office application.

Workaround

Install Microsoft Office 2003, SP3 or later,

-OR-

Follow the steps below.

  1. Click the close button 'x' to close the Excel application.

  2. Click Close button to close the VEE Run Time Error dialog box.

  3. Click close button 'x' to close the VEE application.

  4. Click 'No" button when the "Do you want to save the changes" dialog box appears.

  5. Run the Excel related VEE program again. There should be no such runtime error any more.


VEE May Hang When Loading Programs

VEE May Hang When Loading Programs with Very Large Number of Opened Objects

You may encounter problems when loading a program containing very large number of opened objects. This is caused by exhaustion of Windows user handles.

VEE creates one or more Windows user handles for each object in open view. The maximum number of Windows user handles VEE can create is assigned by Windows OS and is decided by how much resource is currently available.

One work around for this issue is to iconize all objects and close all UserFunctions in your program, which will reduce the number of Windows user handles needed.

See Also

To Reduce the Number of Objects in a Program, To Remove Barriers to Program Performance


User Contributed Programs

User Contributed VEE Programs

These examples are provided as illustrations only and are "as is". Agilent Technologies makes no warranty of any kind in their regard. They have been contributed by VEE users from all over the world. If you are interested in contributing a sample, submit it to vrf-examples@agilent.com. Please document the example thoroughly and let us know if you want your name and/or email address published.

ExcelAsDatabase.vee Use Excel as a 'database' for table lookup.

The Excel workbook consist of five fields (columns) in the Table worksheet: ID, Code, Project, Date and Comment.

The Query worksheet use Excel's DGET functions to lookup data in the table. The lookup value for the query is sent in from VEE and the query result is read back and presented in VEE.
InstrumentAssistant.vee Instrument Assistant example program

This program can be used to find all connected instruments on all configured GPIB and VXI interfaces. The program can also be used to communicate with a selected instrument (only GPIB instruments are supported). Standard IEEE488.1/488.2
commands can be sent in addition to userdefined commands. A history buffer that keep track of sent commands is included. Data can be read from the instrument using ASCII or binary block formats.

This example program use these features of VEE:
* The Dynamic I/O Automation Server
* Programmable Instrument Properties
* I/O configuration saved with the program file
SQLServerUsingADO.vee VEE-Database access

This simple example program illustrates how VEE can use Microsoft ADO (rev 2.1) Automation Server for integration with SQL Server 7.0 databases. SQL Server 7.0 must be available on a remote server or on this system as specified in the Server field. Specify (local) as server if VEE and SQL Server is running on same PC.

The program use SQL's pubs example database by default and:

  • Lists all databases on SQL server by reading the Catalog Schema
  • Finds all tables in one database (pubs) by reading the Tables Schema
  • Allow execution of SQL queries
  • Allow viewing of tables
  • Traps ADO errors from SQL Server
MakeSelections.vee Make a multiple selection popup object

This example program contains a Multiple Selection object allowing the user to make one or more selections from an input
list. VEE's standard selection object only allow single item selection.

VEE_Window_mods.vee This example shows how you can change attributes of the VEE window. It demonstrates:
  1. The import of API functions (Function ImportLib)
  2. The creation of global constants on runtime from a string array (Function CreateGlobals)
  3. The way to find the Window handle of the current VEE application and to change the attributes of the window:
    1. Stay on top
    2. Allow resizing
    3. Show system menu
    4. minimize box enabled/disabled
    5. maximize box enabled/disabled
    6. Hide the entire VEE program for a specified amount of time

Contributed by Georg Nied eMail:info@gn-software.de

Change character in string.vee This function changes one character in a string into a different character.

Submitted by Juan Carlos Martín Castillejos

nidaq.vee Call NI-DAQ library entry points.

This include file has been modified to work the Agilent VEE Import Library object to support the NIDAQ32.DLL.

This modified version is based on the 6.6 version of NI-DAQ.

This is best used in VEE versions 7.0 and earlier as VEE 7.5 and later have added functionality in the Instrument Manager related specifically to NIDAQ.

All Instrument programs below were submitted by Tom Silchia
856xTDFB.vee Extracts trace data from the HP/Agilent 8560E-Series Spectrum Analyzers.TDF B (B-Format):

Return Binary Numbers in Measurement7.0 7.0 The binary (B) format transmits data in measurement units, as binary numbers. This format provides the fastest data transfer and requires the least amount of memory to store data. Each data point is transferred in binary as two 8-bit bytes; the most significant byte is sent first, followed by the least significant byte. Binary data can also be easily converted into measurement data. If speed and memory are important considerations, you may prefer B-format to P-format. Unlike A-block and I-block formats, the B-format does not send a header. The data is sent immediately, and the end-or-identify message (EOI) is sent with the last byte.

856xTDFI.vee Extracts trace data from the HP/Agilent 8560E-Series Spectrum Analyzers. TDF I (I-block format):

Return Indefinite Block-Data Fields in Measurement Units. Very similar to A-block format, the I-block format transmits data in measurement units as binary numbers in an indefinite block-data field of unknown size. Each data point is sent as two 8-bit bytes; the most7.0 significant byte is sent first, followed by the least significant byte. The I-block format also transfers a header before the trace data. The header is comprised of ASCII characters "#", and "I".

856xTDFM.vee Extracts trace data from the HP/Agilent 8560E-Series Spectrum Analyzers. TDF M (M-format):

Return Decimal Numbers in Measurement Units (output only). The measurement units (M) format transfers trace data as ASCII integer values in measurement units, which is the internal format used by the spectrum analyzer. See Figure 5-8 on page 305. The displayed amplitude of each element falls on one of 601 vertical points (with the 601st equal to the reference level). For example, the peak of the signal in Figure 5-8 on page 305 is equal to -10 dBm, or one division below the reference level. This is equal to 540 measurement units (600 measurement units at the reference level, less 60 measurement units for one division down, equals 540 measurement units). There are also ten additional points of overrange. Measurement units range from 0 to 610. A line feed (ASCII code 10) follows data output. The end-or-identify message (EOI) is sent with a line feed. The M-format is faster than the P-format, but most applications will require computer conversion to parameter units. Also, because the M-format transfers data as ASCII characters, the data can be viewed directly.

856xTDFP.vee Extracts trace data from the HP/Agilent 8560E-Series Spectrum Analyzers.

TDF P: Return7.0 Decimal Numbers in Parameter Units The real number, or "P" format allows you to receive or send data as7.0 ASCII decimal values in real-number (parameter) units. This is the7.0 default format when the instrument is turned on, and when instrument7.0 preset (IP) is activated. Numbers are in dBm, dBmV, dBmV, volts, or7.0 watts, as determined using the amplitude units (AUNITS) command.7.0 Default units are volts for linear trace information, and dBm for7.0 logarithmic trace information.7.0 A line feed (ASCII code 10) follows data output. The end-or-identify7.0 message (EOI) is sent with a line feed.7.0 NOTE When using the P-format, be sure to include amplitude units with the7.0 trace data using the AUNITS command.7.0 Real-number data can be an advantage if you wish to use the data later7.0 in a program. However, data transfers using P-format tend to be slow7.0 and require more storage memory (approximately 1200 bytes for binary7.0 and 4800 bytes for real numbers). In some cases, P-format can take up7.0 to four times the amount of controller memory compared to binary7.0 format.

859xTDFBB.vee Extracts trace data from the HP/Agilent 8590E-Series Spectrum Analyzers.

7.0 TDF B enables the binary format. With the binary format, the marker or trace data is transferred as bytes. Of all the trace data formats, TDF B transfers trace data the fastest. The setting of the MDS command determines whether the trace data is transferred as one or two 8-bit bytes.7.0 NOTE : This example utilizes the MDS B (Measurement Data Size) as BYTE. Transferring a single byte (8-bits) per data point. When transferring trace data, MDS B transfers trace data the faster than MDS W because only 401 bytes are transferred. Because MDS B combines two bytes into one byte, some resolution is lost.

859xTDFBW.vee Extracts trace data from the HP/Agilent 8590E-Series Spectrum Analyzers.

TDF B enables the binary format. With the binary format, the marker or trace data is transferred as bytes. Of all the trace data formats, TDF B transfers trace data the fastest. The setting of the MDS command determines whether the trace data is transferred as one or two 8-bit bytes.7.0 NOTE : This example utilizes the MDS W (Measurement Data Size) as WORD. Transferring a word of 2 bytes (8 bits each).per data point. MDS W transfers trace data with no loss of resolution.

859xTDFI.vee Extracts trace data from the HP/Agilent 8590E-Series Spectrum Analyzers.

7.0 TDF I is the I-block data format. With the I-block data format, trace data must7.0 be preceded by “#,” and “I.” The setting of the MDS command determines whether the trace7.0 data is transferred as one or two g-bit bytes. Unlike using the A-block format, you do not7.0 provide the number of data bytes when sending trace data back to the spectrum analyzer.

859xTDFM.vee Extracts trace data from the HP/Agilent 8590E-Series Spectrum Analyzers.

7.0 TDF M is the measurement data format. The measurement data format transfers7.0 trace data in measurement units, and the measurement data can range from -32768 to7.0 + 32767.

859xTDFA.vee Extracts trace data from the HP/Agilent 8590E-Series Spectrum Analyzers.
The A-block format is similar to binary format in that each data point is sent as two 8-bit bytes (this, too, is in the internal representation of measurement data). A-block format also transfers a four-byte header before the 401 points of trace data. These bytes are the ASCII character “f’, “A”, and two-byte number representing the length of the trace data, followed by the data bytes.
8510C_pass_thru.vee

Provides an outline for a method to use the 8510 Pass Thru functionality.

8510_hpgl_Acq.vee | Programming sample for acquiring and dumping the HPGL graphics from the 8510 family network analyzers.
856xPlot2File.vee Acquires an HPGL plotter dump from an 8560E-Series Spectrum Analyzer to a file.

Once acquired the temp.plt file can be viewed via any compatible HPGL file viewer. Note newer versions of Microsoft Office products by default do not include the HPGL viewer. Visit Microsoft's website and search on hpgl 32 bit for downloads that can enable HPGL file imports into Microsoft Word and/or Microsoft Excel.

871xLearn_String.vee Acquire and send the 871x learn string from and to the instrument.

The application is intended to be executed on 8711C, 8712C, 8713C, 8714C and the entire 871xET/ES vector network analyzer families. The program is broken into a main, two UserObjects, and one UserFunction. The UserObject "getLearnString" acquires the learnstring and stores the data to text file, 'C:\learnData.txt". This object has it's own notes detailing operation and execution. The UserObject "sendLearnStringOut" queries the learn string data from the file 'C:\learnData.txt" and then writes the bytes into the analyzer thus recalling the learnString State. This object has it's own notes detailing operation and execution. The "err_check" UserFunction provides a means of confirming that no errors are caused during the program execution. The OK buttons allow the user to configure the analyzer, acquire the learnstring, reset analyzer (to a preset) and then resend the acquired learnstring, confirming proper operation.

8753_freq_data.vee Extract the trace frequency point data from an 8753/8720 family network analyzer.

Use the OUTPLIML command to extract the stimulus and marker data. NOTE the LIMIT test FUNCTION is NOT on! The command provides a means to extract the frequency points.

8753_marker.vee Reading the marker data out of the 8753/8720 family VNAs with several methodologies.

Note that marker data and the validity of the data is a function of the analyzers DISPLAY FORMAT. The first value is the marker reading; the second value may or may not be valid as a function of the DISPLAY FORMAT; the third value is the STIMULUS (frequency or time). For full details refer to the 8753/8720 Programmer's Guide Marker Data section. For this example the FORMAT is LOG MAG, per the manual the second marker value is "insignificant", a.k.a. a place holder, or equivalently JUNK

4395A_Extract_State.vee Extract the state from a 4395A combination analyzer

This application has been tested with the 4395A combination analyzers. The application will catalog the INTERNAL MEMORY and parse all saved files of type state (as indicated by "*.STA" file type). Once the file list has been created, the Agilent VEE application will extract all the *.STA files to the external controller. The *.STA files are binary files which can be sent BACK to the 4395A (either via the PC and VEE, or via 3.5" floppy).

4396b_ascii_out.vee Extract a FORMATTED data trace from a 4395A, 4396A, or 4396B combination analyzers.

The program queries the instrument(s) for the FORMATTED data trace as a "FORM4"(ascii) data transfer. The data trace array size is automatically determined from the queried number of points (a.k.a. "no_poin") and then passed to the real_32 array variable. The program outlines some other Agilent VEE features such as querying the trace START Frequency, STOP frequency and NUMBER of POINTS, and then passing these to a linRamp function (embedded in Agilent VEE) in order to AUTOMATICALLY create the frequency points for each data value. Another feature is the capability to create X-vs-Y plots for displaying the frequency/amplitude data extracted from the analyzer. As a final note the minimum and maximum data values are easily extracted and displayed via Agilent VEE.

4194a_gain_delay.vee | Extract the GAIN and GROUP delay data from the Agilent 4194A impedance analyzer.
4294A_ascii_out.vee Example for the Agilent 4294A Impedance Analyzer.

Outlines methods to acquire Impedance, Phase, Parallel Capacitance, Parallel Conductance, in both FORMATTED display trace data and REAL and IMAGINARY data trace formats.

8753_Limit_test.vee | A method for reporting a limit line failure on the 8753/8720 family of vector network analyzers
8753ES_registerRecall.vee | Outlines a process for recalling instrument states from internal memory on the 8753/8720 family vector network analyzers.
8753ES_NumGroup_OPC.vee | Demonstrates the use of use of *OPC? and NUMG (or number of groups) for the 8753/8720 family of vector network analyzers to coordinate and synchronize end of sweep when averaging is activated within the analyzer.
8753ES_NumGroup_SPOLL.vee | Demonstrates the use of SPOLL and NUMG (or number of groups) for the 8753/8720 family of vector network analyzers to coordinate and synchronize end of sweep when averaging is activated within the analyzer
8753Graphics.vee | Write HPGL TEXT to the 8753/8720 family network analyzers display.
8753LearnStr.vee | Program for reading and writing the binary learn string from and to the 8753 and 8720 family of vector network analyzers.
8757_PassThru.vee | Program for the 8757 Scalar Network Analyzer and compatible signal source. The program outlines a method for using the PassThru mode to access and communicate with the signal source connected to the analyzers "8757 System Interconnect" GPIB buss. This is a dedicated GPIB for controlling the source directly from the 8757 scalar analyzer.
8757_E8257C_ScpiPassThru | Program for the 8757 Scalar Network Analyzer and compatible signal source. The program outlines a method for using the PassThru mode to access and communicate with the signal source connected to the analyzers "8757 System Interconnect" GPIB buss. This is a dedicated GPIB for controlling the source directly from the 8757 scalar analyzer.
4284A_BIN_ASCII.vee | Program for outlining how to extract either ASCII or BINARY data transfers from the 4284A Impedance Analyzer.
4263B_BIN_ASCII.vee | Program for the 4263B LCR meter. Outlines how to acquire either a BINARY or ASCII data transfers from LCR meter.
e5100a.vee | Program for the E5100A low frequency network analyzer. Provides an outline of using the E5100As built in waveform analysis to acquire the statistics for Channel 1 (as GAIN) and Channel 2 (as phase).
E5100A_Resp_Cal_Array.vee | Program for the E5100A low frequency network analyzer outlining how to extract a transmission thru response calibration array (as a FORM4 - ASCII transfer) from the analyzer. The extracted array is saved to a file on the controlling PC.
8753_form2.vee | Program for the 8753 and 8720 family of vector network analyzers. The program provides a tutorial for both synchronizing sweep complete via an SRQ mask and extracting the trace data array as a FORM 2 - REAL 32 binary block transfer.
8753_form3.vee | VEE Sample program for the 8753 and 8720 family of vector network analyzers. The program provides a tutorial for both synchronizing sweep complete via an SRQ mask and extracting the trace data array as a FORM 3 - REAL 64 binary block transfer.
8753_form3_COMPLEX.vee | Program for the 8753 and 8720 family of vector network analyzers. The program provides samples of: synchronizing sweep complete via an SRQ mask; extracting Real and Imaginary trace data array as a FORM 3 - REAL 64 binary block transfer; and how read the array into a variable defined as a COMPLEX array.
8753_form4.vee | Program for the 8753 and 8720 family of vector network analyzers. The program provides a tutorial for both synchronizing sweep complete via an SRQ mask and extracting the trace data array as a FORM 4 - ASCII data array transfer.
8753_hpgl_Acq.vee | Program for acquiring and dumping the HPGL graphics from the 8753 and 8720 family network analyzers.
EPM_Sensor_Status.vee | Program for the EPM E-Series of average sensing RF power meters. The program uses the "STATUS:DEVICE:CONDITION? bit response to determine which channels have sensors connected and if they are connected to either the front or rear panel connections.
EPM_Averages_SPOLL.vee | Program for the EPM E-Series of average sensing RF power meters. The program uses the manual filter mode which allows the user to set the filter length (a.k.a. averages). The program also utilizes an SPOLL to determine when the measurement data is available.
EPM_LoUpLimit_Test.vee | Program for the EPM E-Series of average sensing RF power meters that shows the use of the "STAT:OPER:LLF:SUMM:COND?" (lower limit failure reporting) and the "STAT:OPER:ULF:SUMM:COND?" (upper limit failure reporting) status queries.
EPM_LoadCalTable.vee | Program for the EPM E-Series of average sensing RF power meters. The program outlines how to catalog the list of internal sensor calibration tables, select a table, and then write user calibration factors, at user defined frequencies, to the selected calibration table.
EPM_Meas_SPOLL.vee | Program for the EPM E-Series of average sensing RF power meters. The program uses the MEASURE command which allows the power meter to control the instrument setup. The program also utilizes an SPOLL to determine when the measurement data is available.
ENA_StateRdWrt.vee | Program for the ENA (E5070/E5071) family of network analyzers. Provides examples of cataloging the memory, extracting a state file as a binary block to the PC, and then recalling the binary state file (from the PC) and writing back the binary block to the ENA memory.

ENA_Average_SPOLL.vee

Program for the ENA (E5070/E5071) family of network analyzers. The program is intended to provide a guide for ONE method of detecting an AVERAGE COMPLETE CONDITION on the ENA Series Vector Network Analyzers. An E5071A was tested.
ENA_Fast_SPOLL | Program for the ENA (E5070/E5071) family of network analyzers. The program can be utilized as a launching point in understanding typical trace sweep speeds and data acquisition and transfer speeds as a function of various bandwidths on the network analyzer.


Connecting Objects to Make a Program

This section introduces VEE programs. In Lab 1-1, you will create a VEE program, print the VEE screen, and save the program to a file.

Lab 1-1 Display Waveform Program

A VEE program consists of VEE objects connected in an executable object diagram. The following program displays a waveform.

(If VEE is running, clear the workspace by clicking the New button on the toolbar, or use File [image] New. Otherwise, start VEE and continue.)

1 Document the program. Select Display [image] Note Pad and place it at the top and center of the work area. Click on the editing area to get a cursor. Remove any template information you might have and then enter:

Display Waveform generates a cosine waveform and sends it to a real time display.

You may have to size the Note Pad, depending upon the screen. To size an object, open the object menu, select Size, move the sizing arrow cursor to a corner of the object and drag. You can also click and drag any corner of the object.)

2 Add the Function Generator object. Select Device [image] Virtual Source [image] Function Generator, position the outline on the left side of the work area, and click to place the object. Edit the frequency to 100 by clicking in the Frequency field and typing 100.

3 Add the Waveform (Time) object. Select Display [image] Waveform (Time) and place the object to the right side of the work area as shown below.

In the above figure, the Func label on the Function Generator object denotes a data output pin, and the Trace1 label on the Waveform(Time) object denotes a data input pin. In VEE programs, you connect the data pins among the objects, and this determines the flow of the program.

4 Complete the program by connecting the data output pin on the Function Generator (next to Func on the right side) to the data input pin on the Waveform (Time) display (next to Trace1 on the left side). To do the connecting, move the cursor to one of the pins.

The cursor shape changes when it is near a pin where a connection is allowed. Click the left mouse button, move the mouse cursor to the other pin, and click again. A line is automatically routed between the two pins and the program is complete.

Try moving one of the objects by dragging on its title bar. (Do not drag a pin or terminal, or a line will appear.) The line automatically reroutes to the logical path between the two objects.

If the lines appear to be scrambled, use Edit [image] Clean Up Lines to reroute the lines in the program.

Running a Program

5 Continuing with the same exercise, click the Run button on the toolbar to run the program, or use Debug [image] Run. The program displays a 100 Hz Cosine wave in the Waveform (Time) display as follows. (Your object might have a different frequency, which is not important to the example.)

In addition to the Run button on the toolbar, you can use the Stop, Pause, and Step buttons on the toolbar to control the program. If you pause a running program, use the Resume button (same as the Run button) to resume. You can use the Step Into button on the toolbar to run a program one object at a time.

When instructed to run the program, click the Run button on the toolbar, or press Ctrl+G. Other keyboard shortcuts include the following:

Command | Keystroke Combination
Pause | Ctrl+P
Resume | Ctrl+G
Step Into | Ctrl+T

Changing Object Properties

You have seen how to change some properties of an object by selecting its object menu [image] Properties. You can also change the more common properties of an object directly in its open view. You may have noticed that the Function Generator object has two kinds of fields. A field with an arrow on its right-hand side is a selection field.

6 Continuing with the same example, click Cosine (or the arrow) in the Function field. A drop-down list of selections appears. Click Sine to select the Sine function, noticing that the Function field has changed from Cosine to Sine.

Some fields in dialog boxes do not have arrows. These are entry fields, which become type-in fields when you click them. Just click a field and a cursor appears. You can use standard keyboard and mouse editing techniques to move the cursor and enter a desired value.

7 Click the Frequency field to the right of the value 100, and, while holding the mouse button down, move the mouse to the left to highlight the last 0.

8 Press Delete to delete the last 0, changing the Frequency value to 10. Run the program. It should look like the following figure.

The displayed waveform is now a 10 Hz sine wave. You may want to try changing a few object parameters as follows:

• Click Deg (or the arrow) in the Function Generator object and change the phase units to Rad. Next, click the Phase value field and enter the value PI. Run the program and note the phase shift in the displayed waveform. Then, change the Phase value back to 0 and the units back to Deg.

• The y-axis limits of the Waveform (Time) object are preset to -1 through 1. Click the y-axis name Mag to open a dialog that lets you change the settings. Click the fields for Maximum and Minimum to change the limits to 2 and -2. The waveform is displayed within the new limits. To change similar parameters for the x-axis scale, click Time.

Printing the Screen

9 Continuing with the same example, to print the screen, select File [image] Print Screen. a Print dialog box appears.

When you click OK, VEE prints the screen on the default printer named in the dialog box. You can select another printer, change the print range, and enter the number of copies. Click the Properties button for more selections. Different print drivers may use different dialog boxes. For further information about using Windows dialog boxes, see Microsoft Windows Help.

You can also click the Print Screen button on the toolbar to print the screen directly.

Saving a Program

You can save a program at any time. (You can save whatever is in the work area, whether it is a complete program or not).

10 Continuing with the same example, select File [image] Save As... and complete the dialog box.

A dialog box entitled Save File appears.

11 By default, VEE for Windows saves files in the VEE Programs sub-directory in your My Document directory. To save the current program, type in the name simple-program in the File name field and click Save. If you do not type it in, VEE automatically adds the .vee extension to the file name.

note

You can use the long file names allowed by Windows Vista, Windows 2000, and Windows XP.

In the Save File dialog box, you can make changes to the different fields as follows:

File Save Option

Description

Save in

You can change the directory or drive by opening the drop-down menu. Double-click a folder to open it.

File name

Type in a file name of your choice.

Save as type

VEE programs are normally saved with the .vee extension, but you can change the file type if you wish. If you type a file name without the extension, the .vee is automatically added.

Save colors and fonts with program

(Optional) If you have changed program colors and fonts, using the Default Preferences menu, and you want others who load the program to get the colors and fonts you selected (rather than their defaults), click to check this item.

When checked, VEE saves the changes you have made to the default configuration as part of the program.

Save I/O configuration with program

(Optional) If you have configured an instrument in the Instrument Manager, and you want others who load the program to get the instruments you configured rather than their defaults, it is recommended that you check this item.

When checked, VEE saves the I/O configuration as part of the program.

note

To re-save the program to the same file name, click the Save button or press Ctrl+S at any time (File [image] Save). It is a good idea to save files frequently while you are developing a program. To save a program that you have edited to a different file name, press Ctrl+W or File [image] Save As.

Exiting (Quitting) Agilent VEE

Select File [image] Exit to close the VEE application window. Another shortcut is to press Ctrl-E to exit VEE, or click on the x button at the right end of the title bar.

You will probably not need to use the following techniques, but if VEE stops responding to the mouse or keyboard, follow these instructions:

Operating System | Method
Windows 2000, Windows XP, Windows Vista | Press Ctrl-Alt-Delete and click the Task Manager button. Select VEE in the Applications list and click End Task.

Re-Starting Agilent VEE and Running a Program

1 Click Start [image] Programs [image] Agilent VEE Pro

2 Select File [image] Open and complete the Open File dialog box.

The format is the same as for the Save File dialog box. Note that the default directory for user programs is the VEE_USER directory, unless you specified something else during installation. VEE opens the program in the Main window.

3 Click the Run button. It looks like a small arrowhead, and is located on the tool bar below the Debug menu as shown below.

Run Button

note

The command vee85.exe -r filemame starts VEE and automatically runs the program specified by filename. For example, you could create an icon on the Windows desktop and set its Properties [image] Shortcut to run a particular VEE program. An operator could then double-click an icon on the desktop to start VEE and run a program automatically. For more information, refer to the Windows Help information about commands and prompt paths.

Managing Multiple Windows in the Workspace

Most of the discussion so far has focused on the work area in the Main window. However, large VEE programs can contain multiple windows inside of the Main window. For example, a program may contain objects that you define, such as UserObjects and UserFunctions. (You can think of UserObjects and UserFunctions as subroutines or subprograms to the main program. UserObjects and UserFunctions are discussed in more detail in the section “Lab 2-1: Creating a UserObject"). They are mentioned here to show how VEE helps you manage programs that have multiple windows.

Following figure shows a program with four windows. Each window has an icon (which provides menu commands), a title, and three buttons; minimize, maximize, and close. Maximizing a window makes it occupy the available area in the VEE workspace. Minimizing a window makes its icon appear along the bottom of the VEE workspace. Closing a window removes it from the workspace. VEE highlights the working window title bar.

In above figure, the Program Explorer lists the hierarchy of the program. This built-in modular structure allows easy access to all parts of the program.

If the Program Explorer is not displayed, click View [image] Program Explorer.

To bring the Main window forward at any time, click on it or double-click its icon in the Program Explorer.

note

If you close the Main window in VEE, you can display the Main window again by selecting View [image] Main.

See Also

U nderstanding Pins and Terminals, Working with Objects, Interacting with Agilent VEE, How Agilent VEE Programs Work


How Agilent VEE Programs Work

Lab 1-2: Viewing Data Flow and Propagation

Lab 1-3: Adding a Noise Generator

Lab 1-4: Adding an Amplitude Input and Real64 Slider

Lab 1-2: Viewing Data Flow and Propagation

In VEE, the general flow of execution through a program is called propagation. Propagation through a program is not determined by the geographic locations of the objects in the program, but rather by the way the objects are connected. Propagation is primarily determined by data flow, which, in turn, is determined by how the data input and output pins of the objects are connected.

note

In other programming languages such as C, BASIC, or Pascal, the order in which program statements execute is determined by a set of sequence and selection rules. Generally, statements execute in their order of appearance in the program unless certain statements cause execution to branch to another statement or thread of code.

The rules of data flow in a VEE program are:

• Data flows from left to right through an object. This means that on all objects with data pins, the left data pins are inputs and the right data pins are outputs.

• All of the data input pins in an object must be connected. Otherwise, an error occurs when the program runs.

• An object will not execute until all of its data input pins have received new data.

• An object finishes executing only after all connected and appropriate data output pins have been activated.

In VEE, you can change the order of execution by using sequence input and output pins. However, you do not normally need to use sequence pins except for special cases. It is generally best to avoid using the sequence pins. If possible, let data flow control the execution of the program.

To see how data flow works, open the program simple-program.vee by clicking the Open button on the toolbar. (The program simple-program.vee is described in “Lab 1-1 Display Waveform Program".) Now run the program. It should appear as follows, although you may have different values for parameters.

note

The VEE programs for many of the lab exercises and programming examples are included in VEE, under Help [image] Open Example... Manual [image] UsersGuide.

The data output pin of the Function Generator object is connected to the data input pin of the Waveform (Time) object. When you run the program, the Waveform (Time) object will not execute until it receives data from the Function Generator object. This is a simple example of data flow.

Lab 1-3: Adding a Noise Generator

Add a “noisy sine wave” by adding a Noise Generator object to simple-program.vee as follows.

1 Delete the line connecting the Function Generator and Waveform (Time) objects in the original program. Click the Delete Line button on the toolbar and then click the line. Or, press and hold Shift+Ctrl and click the line.

2 Minimize the Function Generator to its icon.

3 Add the Noise Generator object (Device [image] Virtual Source [image] Noise Generator).

4 Add the A+B object, using Device [image] Function & Object Browser.

The Function & Object Browser is shown below. Select Operators => Arithmetic => +. Click Create Formula and place the object in the work area between the Function Generator and the Waveform (Time) object. Minimize the A+B object.

1 Connect the input and output pins.

2 Run the program.

Notice that the A+B object does not execute until the Function Generator and the Noise Generator objects execute. However, it does not matter whether the Function Generator or the Noise Generator executes first, because the result is the same.

Once both of the A+B input data pins receive data, the A+B object executes, summing the two signals and outputting the result to the Waveform (Time) object.

Note

The data flow in a VEE program determines its execution.

To see the order of execution, turn on the Debug commands Show Execution Flow and Show Data Flow, or click their respective buttons on the toolbar. Run the program again. Each object highlights when it executes and a small, square marker moves down the lines to show data flow.

note

Show Execution Flow and Show Data Flow can be enabled together or individually by clicking their toolbar buttons or their commands in the Debug menu. Normally, you should turn these commands off because they slow down the program.

Lab 1-4: Adding an Amplitude Input and Real64 Slider

Add an amplitude input and a Real64 slider to simple-program.vee.

1 Click on the object menu or press Ctrl+A with the mouse pointer in the “terminal area” at the left side of the Noise Generator. The dialog box appears for you to add an input.

2 Select Amplitude by clicking OK—an Amplitude input terminal appears.

Now that the Noise Generator object has an amplitude input pin, you can input this data as a real number. VEE provides an object that makes this easy, called a Real64 Slider, which is located in the Data menu. (You could also use the Real64 Constant object or a Real64 Knob.)

3 Add a Real64 Slider object (Data [image] Continuous [image] Real64 Slider) and connect its data output pin to the Amplitude terminal as follows. Run the program.

Try changing the amplitude of the noise, by dragging the slide control on the Real64 Slider object. The amplitude of the noise does not change until you run the program. The noise component of the displayed waveform depends on the Real64 Slider output value.

Again, data flow determines the order of execution. The Noise Generator cannot execute until the Real64 Slider executes. The A+B object cannot execute until both the Function Generator and the Noise Generator execute, but it does not matter which one executes first. Finally, the Waveform (Time) object executes only after the A+B object has executed.

note

You can display the value of an output by using the mouse to hover over the line. For example, hovering over the line from the Real64 Slider object to the Noise Generator displays a value of 0.401. Notice that the value on the line (0.401) matches the value shown on the Real64 Slider, as shown in the following figure. (Note that the objects are shown in iconized view.)

4 Re-save the program to simple-program.vee. You will add some more features to it in later labs.

Copyright (c) 1991-2006 Agilent Technologies, Inc.


General Techniques

Inside the Main VEE program, you can create logical groups of objects, called UserObjects. A UserObject is created by placing a logical group of objects in a UserObject window. Inside the UserObject window, you connect inputs and outputs in the same way as the main program. The UserObject itself is connected to other objects in the main program with inputs and outputs, like any other object.

The idea in developing a UserObject is to create a unique context that performs a useful purpose within the main program. Besides conserving space in the main work area, you can make the program more understandable by giving it structure.

A VEE program can contain many UserObjects nested within the Main program. Each UserObject has an icon view which resides in the Main window. To associate the icon views of the UserObjects in the main program with their associated UserObject windows, name UserObjects in their edit windows, which also names them in their associated icon view. For example, if you name a UserObject AddNoise, its icon window in the Main program and the title bar on the UserObject will both read AddNoise. The following exercise teaches you how to create a UserObject.

Lab2_1: Creating a UserObject

Lab2_2: Creating a Dialog Box for User Input

Lab2_3: Using Data Files

Lab2_4: Creating a Panel View

Lab2_5: Mathematically Processing Data

Lab2_6: Generating a Random Number

Lab2_7: Setting and Getting a Global Variable


Lab 2-1: Creating a UserObject

There are a couple of ways to create a UserObject in a VEE program:

• Select Device [image] UserObject from the menu bar to bring up an empty UserObject icon in the Main window, and add objects to it. If you double-click the UserObject icon, it is displayed in open view as follows.

• Select objects within a program and then create a UserObject from them, by selecting the objects and clicking Edit [image] Create UserObject.

Once you have created a UserObject, it is part of the main program. The UserObject window can be displayed as an icon, in open view, or minimized at the bottom of the screen.

• Close the window by clicking the close button, and the UserObject is displayed as an icon in the main window.

• Maximize the window by clicking its maximize button, and the UserObject window will occupy the entire available area in the VEE workspace.

• Minimize the window by clicking its minimize button. The minimized UserObject is displayed along the bottom of the VEE workspace.

Note

The icon view of the UserObject always resides in the Main window, and you can connect its pins to other objects in the Main window.

Now, you will create a UserObject for a program.

1 Open the program (simple-program.vee ) you created in “Lab 1-4: Adding an Amplitude Input and Real64 Slider". The program should appear in the main work area.

2 Remove the Real64 Slider from the program. (It is not used in this exercise.) Click to open the Real64 Slider Object Menu, and select Delete, or double-click on the Real64 Slider Object Menu button.

NOte

If you run the program again now, with the Real64 Slider object removed and the input pin still on the Noise Generator, you will get a VEE error message that the input pin Amplitude on the Noise Generator is not connected. Remember, all input pins must be connected for a VEE program to run.

3 In the Noise Generator object, click the Object Menu button or click the right button over the object to open the object menu. Select Delete Terminal [image] Input, and in the dialog box for Choose an input to delete with Amplitude highlighted, click OK.

4 Rename the program by choosing File [image] Save As... and type in the new name usrobj-program1.vee.

5 Then, minimize the Noise Generator object and rearrange the objects as follows.

6 Select the Noise Generator and A+B objects, using the shortcut Ctrl+left mouse button. Click Edit [image] Create UserObject. A dialog box appears labeled Create UserObject. (You could rename the object by typing in a new name if you wish. For now, click OK to create the UserObject.)

The UserObject will contain the Noise Generator and A+B objects in the UserObject edit window, and will be automatically created in the Main window with the appropriate input and output pins and connections.

Position the icons in the upper left of the UserObject by simply pressing the Home button on the keyboard.

note

Rearranging the positions of the objects before executing Create UserObject is one of convenience. If you do not collect the objects to be included into one area, the UserObject will size itself to encompass all the selected objects. You can then rearrange and resize the work area of the UserObject and move the UserObject to an appropriate place in the work area. However, the cleanup is easier if you place the objects logically beforehand.

note

You can use Edit [image] Clean Up Lines to clean up the line routing within a program. This command is context dependent. To clean up the lines for the UserObject, it must be the active window. Click the UserObject window, then, use Edit [image] Clean Up Lines.

Creating a UserObject in its edit window and then using the icon view of the UserObject lets you save screen space.

7 To help you keep track of the UserObject, change the title from UserObject to AddNoise. Double-click the title bar and enter the new title in the properties dialog box. Following figure shows how this makes the program easier to follow.

To get to any object's Properties dialog box quickly, just double-click its title bar.

8 Click the Run button to display the noisy cosine wave.

Note that AddNoise is minimized, and appears in icon form at the bottom of the work space. To minimize AddNoise, click on the minimize button in its title bar, shown as the underline symbol (_).

The key to effective UserObjects is to make sure they serve a logical purpose within the program. This unique object is not just a space saving device, but rather a way of structuring a program. UserObjects help you use “top-down” design in VEE programs. VEE also includes an object called a UserFunction, which is a re-usable code module. For more information about UserObjects and UserFunctions, refer to

For more information about UserObjects, select Help [image] Contents and Index from the VEE menu bar. Then, browse How Do I..., Tell Me About..., or Reference.

You will continue with this example in the following section. However, if you want to quit now, save the program as usrobj-program3.vee.


Lab 2-2: Creating a Dialog Box for User Input

If it is not already open, open the program usrobj-program3.vee.

In the Data [image] Dialog Box submenu are six choices for dialog: Text Input, Int32 Input, and Real64 Input, as well as Message Box, List Box, and File Name Selection boxes. In each case for text, integer, and real input, a dialog box helps you configure the prompt or label, default value, value constraints, and error message. Once you include one of these dialog boxes, a pop-up input box will appear when the program is run.

1 Select Data [image] Dialog Box [image] Int32 Input and place it to the left of the Function Generator. Change the Prompt/Label field to Enter Frequency:. (Remember to click and drag over the field to highlight it first.) Change the Default Value to 100.

You can also double-click an input field to highlight an entry.

2 Change the Value Constraints to 1 on the low end and to 193 on the high end. Change the error message to reflect these new values. Finally, iconize the Int32 Input object.

3 Open the Object Menu for the Function Generator, and choose Add Terminal [image] Data Input. In the dialog box for Select input to add, choose Frequency and click OK.

4 Connect the top output pin of the Int32 Input object to the input pin on the Function Generator. Notice that Frequency can only be changed through the input pin now, and you can no longer edit the Frequency input field. The program should look like this.

5 Run the program. The input box for Int32 Input appears, with the instruction Enter Frequency:. Try running the program with different frequencies in the input box. Simply click and drag the pop-up box to control where it appears.

You will get an error message box if you enter frequencies above 193. Notice that you get the exact error message that you configured.

You will continue with this example in the following section. However, if you want to quit now, save the program as usrobj1-program4.vee.

note

The VEE programs for many of the lab exercises and programming examples in this manual are included in VEE, under Help [image] Open Example... Manual [image] UsersGuide.


Lab 2-3: Using Data Files

You can write data from VEE to a data file and read the data in a file into VEE by including the To File and From File objects in the program. For example, add a To File object to the detail view of the program that you have been building.

If it is not already open, open the program usrobj-program4.vee.

1 Select I/O [image] To [image] File and place it in the Main work area.

2 Change the default filename, myFile, to wavedata.

If there is no check mark to the left of Clear File At PreRun & Open, then click on the small input box. To File defaults to appending data to the existing file. In this case, however, you want to clear the file each time you run the program. The To File object should now look like this.

3 Double-click on the area labeled Double-Click to Add Transaction to write the data. The above dialog box appears. Click the TEXT field (or its arrow) to show the drop-down list of data types and click CONTAINER. Click OK. Notice that when you click OK in the I/O Transaction dialog, an input pin a is automatically added to the To File object.

Examine Help in the To File object menu to see the other options for the transaction besides WRITE CONTAINER. Transactions are discussed in more detail in Help => Contents and Index => reference => I/O Transactions.

4 Connect the data output pin of the AddNoise UserObject to the data input pin of To File. The program should now look like this.

note

You can connect one data output pin to several data input pins.

5 Click the Run button on the tool bar again to test the program. The program now displays the noisy cosine wave output by the AddNoise UserObject and writes a container of waveform data to the file wavedata.

Double-click the To File object to get the open view, then double-click the input terminal a to examine its contents. You should see an array of 256 points.

Add a From File object to the program to read the data back.

6 Select I/O [image] From [image] File and place it in the Main work area. Add a read transaction to READ CONTAINER x and change the file name to wavedata (the procedure is the same as for To File). Then, delete the line between AddNoise and the Waveform (Time) object, and connect the objects as shown below. The sequence line between To File and From File ensures the data is written to the file before it is read.

7 Run the program. It should look similar to above. Save the program as usrobj-program.vee.


Lab 2-4: Creating a Panel View (Operator Interface)

After you develop a program, you may want to create an operator interface. To do so, create a panel view of the program. This exercise uses the program, simple-program.vee, you created in “Lab 1-2: Viewing Data Flow and Propagation".

1 Open the program simple-program.vee. The program should look like this.

2 Select the objects that you want to appear in the panel view, which acts as the operator interface. Press and hold Ctrl while clicking on all the objects you want to select. (Make sure no object is accidentally selected.) In this case, select the Real64 Slider and Waveform (Time) objects. They will each now have a shadow to indicate they are selected.

3 Click the Add to Panel button on the toolbar to add the selected objects to the panel (or use Edit [image] Add To Panel). A panel view appears, showing the two objects that you added to the panel.

You can size and move the objects in the panel view to appropriate locations to create a panel similar to the one shown below.

4 Press the To Detail button in the upper left Main window title bar to go to the detail view. Click the To Panel button to return to the panel view.

The detail view is the normal window in which you edit a program. You can move, resize, or delete objects in the panel view independently from the detail view. The detail view is used to develop a program and the panel view is used to provide an operator interface.

5 Save the program as simple-program_with_panel.vee.

You can practice making some changes to the panel view as follows:

  • To change colors on the panel, select Properties from the Main window object menu in panel view. Select the BackColor property, and select the color you want.

  • To change colors or fonts on any object, just double-click its title bar to get the Properties window. Then click the Colors or Fonts property you wish to change.

  • To give a raised appearance to objects in the Panel view, open the Properties window for that object and select Raised under the Border property.

  • To change the name of the Panel view, open the main Properties window and change the Title property to whatever you wish. The name you enter will be displayed when the program executes.


Lab 2-5: Mathematically Processing Data

VEE provides extensive built-in mathematical capabilities and data type support, as well as all the data and signal processing power of MATLAB. For more details, refer to Processing Data.

Using Data Types

VEE supports several data types, including text, integer and real numbers, and several types of complex and coordinate numbers. You have already seen how the A+B object can add two waveforms together in earlier examples. Mathematical operators, such as addition (+), can act on several data types and can even act on mixed data types.

For example, to create the following program clear the Main window, place the following objects in the Main window, and connect them as shown, noting the following information.

1 Select File [image] New to clear the work area.

2 Add a Real64 Constant object by selecting Data [image] Constant [image] Real64.

3 Add a Complex Constant object by selecting Data [image] Constant [image] Complex.

4 Add an A+B object. Select Device [image] Function & Object Browser to get the Function & Object Browser. Then, select Operators => Arithmetic => +. Click Create Formula to create the object.

5 Add an AlphaNumeric object by selecting Display [image] AlphaNumeric. Connect the objects as shown below. Type in the value 1.53 in the data entry field of the Real64 Constant object and the complex value (2,1) in the Complex object. Run the program and you should get the result like follows.

VEE automatically converts the data as needed and then performs the addition in the A+B object. The real value, 1.53, is converted to the complex value (1.53,0), which is then added to the complex value (2,1). The result, (3.53,1) (a complex number), is displayed in the AlphaNumeric object.

note

Normally, VEE automatically handles all data type conversions. For more information, select Help [image] Contents and Index from the VEE menu bar. Then, browse How Do I..., Tell Me About..., or Reference.

Using Data Shapes

VEE supports a variety of data shapes, such as scalars and arrays. Unlike most programming languages, VEE objects can operate on an entire array, rather than on only one element.

The following program creates a one-dimensional, ten-element array, calculates the median of the 10 values, and then displays the median value.

1 Select File [image] New to clear the work area.

2 Add a For Range object, by selecting Flow [image] Repeat [image] For Range.

3 Add a Sliding Collector object, by selecting Data [image] Sliding Collector.

4 Add a median(x) object. Select Device [image] Function & Object Browser. Then, select Built-in Functions => Probability & Statistics => median and click Create Formula.

You can display the Function & Object Browser by clicking the fx button on the toolbar.

5 Add an AlphaNumeric object, by selecting Display [image] AlphaNumeric. Connect the objects like below

. Run the program. If you have not changed any of the inputs on the objects, you should see the result displayed above

Using the Formula Object

VEE provides mathematical operators and functions which are documented in the Reference part of online help. Select Help [image] Contents and Index. Then, select Reference and browse the items as desired.

The predefined operator and function objects are available via Device [image] Function & Object Browser (or fx on the toolbar). Click Create Formula to create the object.

Besides using predefined operators and functions, you can create any valid VEE mathematical expression within the Formula object, which is found under the Device menu. In this section, you will create a program using a Formula object. To begin, clear the Main window and follow these steps.

1 Add the Function Generator object to the Main window and modify it to produce a 100 Hz sine wave. Select Device [image] Virtual Source [image] Function Generator.

2 Select Device [image] Formula to add the Formula object to the Main window. Add a second input (B) to the object by putting the mouse pointer in the input terminal area and clicking Ctrl+A.

3 Type the mathematical expression abs(A)+B in the entry field.

4 Select Data [image] Constant [image] Real64 to add a Real64 Constant object to the Main window. Type in the value 0.5.

5 Select Display [image] Waveform (Time) and set the y-axis scale to -2 through 2. Set Automatic Scaling to Off. To get the dialog box for these parameters, click Mag.

6 Connect the objects as shown below. Run the program.

When you run the program, the Formula object takes the waveform input A and the real value B, and adds B to the absolute value of A. In effect, the expression abs(A)+B “rectifies” the sine wave and adds a “dc offset.” You could have produced the same effect by using the A+B and abs(x) objects, but it is easier to read an expression in a Formula object. (This also saves space.)

Try double-clicking the input and output terminals of the Formula object. Note that the real scalar on input B is added to each element of the waveform data (a one-dimensional array) on input A, and the resulting waveform is output on the Result terminal.

note

To augment VEE’s extensive math capability, there are hundreds more mathematical functions available through MATLAB Script integration. Browse through these functions in the Function & Object Browser. For more information about using MATLAB functions, refer to “Using MATLAB Script in Agilent VEE".


2-6: Generate a Random Number

1 Document the program:

a Select Display [image] Note Pad and place it at the top center of the work area. Click on the editing area to get a cursor and remove any template that might be there. Then enter:

This program, Random, generates a real number between 0 and 1, then displays the results.

2 Select Device [image] Function & Object Browser. Select Built-in [image] All [image] random. Click Create Formula. Place the object in the work area and click to place the object.

3 Click Data [image] Constant [image] Int32 and place it to the left of random. Open the Int32 object menu, click Clone, and put this below the other Int32 object. Double-click the 0 to get a cursor, then enter 1. Connect the constant object with 0 to the low input pin of random, and connect the constant 1 to the high input pin.

4 Select Display [image] AlphaNumeric and place it to the right of the random object. Open the object menus and select Help to understand the objects better.

5 Connect the random object output pin to the AlphaNumeric input pin. A data line appears, connecting the two objects.

note

As you move the mouse pointer with the line attached near the target pin, a box highlights the pin. Then you click again to complete the connection.

note

If for some reason you want to terminate the line connecting operation before you have completed the link, double-click the mouse and the line will disappear.

6 Click the Run button on the tool bar, and you will see a random number displayed as follows.

7 Select File [image] Save As..., type Random.VEE, and click OK. This name will appear next to VEE in the title bar when you open it in the future.


2-7: Setting and Getting a Global Variable

This program gives you more practice in the basic mechanics of building a VEE program, and introduces global variables. You can use the Set Variable object to create a variable that can be retrieved later in the program using a Get Variable object. You can use any VEE data type. This example uses a number of type Real64. (For more information about VEE data types, refer to Data Types)

1 Select Display [image] Note Pad and place it at the top-center of the work area. Click on the upper left-hand corner of the editing area to get a cursor, remove any template that might be there, and then enter the following information:

Set and Get a Global Variable prompts the user to enter a real number. The variable, num, is set to this real number. Then num is recalled and displayed.

2 Select Data [image] Constant [image] Real64 and place it on the left side of the work area. Open the object menu and examine the Help entry.

3 Open the Real64 object menu and select Properties. Change the title to the prompt, Enter a Real Number:, then click OK.

note

This exercise uses one of the Constant objects for an input dialog box by simply changing its title to a prompt. This is a common technique for getting user input. You could use Data [image] Dialog Box [image] Real64 Input. Also, you can double-click on the title bar to get the Constant Properties dialog box.

4 Select Data [image] Variable [image] Set Variable and place it to the right of the Real64 object. Double-click globalA to highlight it, then enter num. Notice the name of the object changes to Set num.

This means that the user will enter a real number in the Real64 object. When the user clicks the Run button, the number will be set to the global variable, num.

5 Connect the data output pin of the Real object to the data input pin of the Set num object.

6 Select Data [image] Variable [image] Get Variable and place it below the Set num object. Change the variable name to num. Notice the name of the object changes to Get num.

7 Connect the Set num sequence output pin to the Get num sequence input pin.

note

A global variable has to be set before you can use it. Therefore, you need to use the sequence pins in this case to make sure that the variable num has been set, before you retrieve it with Get num.

8 Select Display [image] AlphaNumeric and place it to the right of the Get num object.

9 Connect the Get num data output pin to the AlphaNumeric data input pin.

10 Enter a real number and click the run button on the tool bar. The program should look similar to the following figure.

11 Select File [image] Save As... and name the program global.vee.


Lab 3-1: Configuring an Instrument without the Instrument Present

Lab 3-1: Configuring an Instrument

With VEE you can develop programs without the instruments present. In this exercise, you will configure an oscilloscope for use with a panel driver. Then you will add the physical instrument to the configuration.

Configuring an Instrument without the Instrument Present

1 Select I/O [image] Instrument Manager.... Move the dialog box to the upper-left work area by clicking and dragging its title bar.

note

If you have any instruments connected and powered on, VEE can find the instruments and automatically find the drivers for them. For more information about automatically finding and configuring instruments, refer to Help [image] Welcome [image] Tutorials in the main VEE screen.

By default, there are no instruments configured, and this example assumes that no instruments appear in the Instrument Manager list.

2 In the Instrument Manager dialog box, make sure My Configuration is highlighted, and click Add... under Instrument. The Add Interface/Device dialog box appears. Click OK, the Instrument Properties dialog appears.

3 Change the name to scope, leave all the other defaults as they are, and click Advanced.... The Advanced Instrument Properties dialog box appears.

The entries in the General folder are as follows:

Entry | Description
Timeout | The maximum number of seconds allowed for an I/O transaction to complete before you get an error message.
Live Mode | Specifies whether there is live communication with the instrument. Set this to OFF unless you have an instrument present. VEE defaults to the ON setting.
Byte Ordering | Specifies the order the device uses for reading and writing binary data. The field toggles between Most Significant Byte (MSB) first or Least Significant Byte first. All IEEE488.2-compliant devices must default to MSB order.
Description | Enter any description here. For example, if you want the instrument number on the title bar, enter the number.

4 Toggle Live Mode to OFF. Then click the Panel Driver folder, and the dialog box appears.

5 Click the field to the right of ID Filename to obtain a list box entitled Read from what Instrument Driver?. This list includes all of the panel driver files loaded with your revision of VEE in the directory specified.

note

You need to install the panel drivers from the VEE CD-ROM to complete the example. The *.cid files signify the compiled instrument driver files.

6 Scroll down the list to highlight hp54504a.id, then click Open. Above figure shows this instrument already selected. You can also double-click on a highlighted file to select it.

The other entries in the Panel Driver folder are as follows:

Panel Driver Entries | Descriptions
Sub Address | Leave this field blank. Sub Address is used only by non-VXI cardcage instruments for identifying plug-in modules.
Error Checking | Leave the default setting ON. Error Checking can be turned off for extra throughput, but then it does not check for I/O errors.
Incremental Mode | Leave the default setting ON. Incremental Mode can also be turned off, which sends the entire instrument command string for the instrument state each time you change a setting.

7 Click OK to return to the Instrument Properties box. Click OK.

The list of available instruments should now include an instrument configuration named scope, using the driver file hp54504a.cid. The instrument does not have a bus address specified, because it is not live at present. You can develop the program in this mode, and add an address later, when you are ready to connect the instrument to your computer.

Press the Tab key after typing in a field to move to the next field, and press Shift-Tab to move to the previous field. Pressing Enter is equivalent to clicking OK. VEE closes the dialog box.

8 Click Save to close the Instrument Manager box. (You could also click Panel Driver under Create I/O Object to put it in the program immediately, and VEE would save the configuration automatically.)

You have now added the HP 54504A oscilloscope named scope to the instrument list. You can use this driver while programming, even though the actual instrument is not present.

Selecting an Instrument to Use in a Program

1 Select I/O [image] Instrument Manager....

2 Highlight the selection scope(@(NOT LIVE)), then click Panel Driver under Create I/O Object.

Note

In the Instrument Manager, you can often create different types of objects under Create I/O Object, depending on the type of instrument configured. For example, if you had chosen Direct I/O rather than Panel Driver for this exercise, you would get a Direct I/O object with the name scope(@(NOT LIVE)).VEE also provides a Component Driver, which uses a subset of the functions provided by a Panel Driver. (For more information, refer to I/O Configuration Techniques.)

3 Place the outline of the scope panel and click to place it. The display should look similar to following figure.

You may now use the panel driver in the program like any other VEE object.

Adding the Physical Instrument to the Configuration

1 Select I/O [image] Instrument Manager...., and highlight scope. Under Instrument... click Properties.

2 Double-click the VISA Address field to highlight the current entry and type the same instrument VISA address that is configured in Agilent Connection Expert. For example, GPIB0::20::INSTR.

3 Click Advanced: and toggle Live Mode to ON, then click OK. Click OK to close the Instrument Properties box.

4 Click Save to save the changes.


Lab 3-2: Changing Settings on a Panel Driver

Lab 3-2: Using a Panel Driver

These exercises use the HP 3325B Function Generator as the example. The principles are the same in using any VEE panel driver. By using a panel driver instead of programming an instrument directly, you save time developing and modifying programs. Changes in the instrument settings are made through menu selections or by editing fields in dialog boxes. If the instrument is connected and Live Mode is ON, the changes you make will register on the instrument.

To use a panel driver in a program, add inputs and/or outputs as needed and connect the panel driver to other objects. You can use several instances of the same driver in a program to set the instrument to different states. In VEE, you can iconize a panel driver to save space, or use the open view to display the instrument settings. You can also change settings while a program is running.

Changing Settings on a Panel Driver

1 Select I/O [image] Instrument Manager.... Select My Configuration, then click Add... under Instrument to display the Instrument Properties dialog box, and edit the information as follows:

Setting | Description
Name | Edit to fgen and press the Tab key twice to move to the Address field.
Address | Change to 713, or the address you want on the bus.

2 Click on Advanced. In the General folder and toggle Live Mode to OFF.

3 Click on the Panel Driver folder and set ID Filename: to hp3325b.cid. Click OK twice to return to the Instrument Manager.

4 Under Create I/O Object, click Panel Driver. Place the object on the left side of the workspace. (This process would be the same regardless of the instrument, as long as the instrument had been configured and added to the list.)

note

You are programming without the instrument attached. If the instrument was attached, you would edit the configuration to the proper address.

5 Click Sine in the Function field to get a pop-up menu, and then select Triangle

6 Click the field to the right of Frequency.

7 Type 100 in the Continuous component FREQUENCY dialog box that appears, and click OK. Note that the Frequency setting has now changed.

You can use the same methods to change the instrument settings on any driver. If the instrument is configured with an address and Live Mode is ON, every change you make in the driver panel is reflected by the instrument.

Moving to Other Panels on the Same Driver

Most drivers have more than one panel to simplify the user interface. To move to a different panel, click Main Panel in the object to get a menu of panels.

1 In the Panel Driver object, click Main Panel and select Sweep in the Discrete Component MENU.

2 Click OK to display the Sweep Panel. You can also look at the other panels to see what is available.

3 Click OK to return to the Main Panel.

Adding Inputs and/or Outputs to a Panel Driver

In addition to interacting with the panel directly, you can control settings or read data from an instrument in a program by adding data inputs and/or outputs to the driver. The input and output areas are shown below..

1 Place the mouse pointer over the data input area of the function generator instrument panel, and press CTRL-A to add a data input terminal. A list box of the instrument components appears.

2 Select the desired component from the menu presented.

note

You could also open the object menu and select Add Terminal by Component [image] Select Input Component. Then select the desired component field on the driver.

Follow the same process to add a data output, by placing the mouse pointer in the data output area.

Deleting Data Input or Output Terminals

Place the mouse pointer over the terminal and press CTRL-D.

note

You could also open the object menu and select Delete Terminal [image] Input... from the object menu and choose the appropriate input from the menu presented.

On Your Own

Set a state on the HP 3325B Function Generator, or any other function generator available. Change the Function setting to a Square wave. Add input components for Amplitude and Frequency. Create input dialog boxes for the amplitude and frequency and modify the titles to prompt the operator. Enter different values for the amplitude and frequency, and run the program to see if the settings have changed after operator inputs. (If an instrument is attached, then its settings will change if Live Mode is ON.)


Lab 3-3: Using Direct I/O

If there is not a driver available for a particular instrument, or you want higher throughput, use the Direct I/O object.

Using Direct I/O

In this exercise, you will configure the HP 3325B function generator using Direct I/O.

1 Select I/O [image] Instrument Manager....

2 Highlight the fgen(@(NOT LIVE)) entry and select Instrument [image] Properties.

3 Click on Advanced. Select the Direct I/O folder. Look through the options available, then click OK to return to Instrument Properties, then OK again to return to the Instrument Manager.

note

This example uses the GPIB interface (IEEE488). To configure Serial, GPIO, or VXI instruments, refer to I/O Configuration Techniques.

4 To place the object on the screen, make sure that fgen(@(NOT LIVE)) is still highlighted, and click Create I/O Object [image] Direct I/O.

To use a Direct I/O object in a program, you have to configure I/O transactions. The next section explains writing text commands, reading data, and uploading/downloading instrument states.

Sending a Single Text Command to an Instrument

To send a single text command to an instrument, type in the appropriate string. Most GPIB instruments use alphanumeric strings for commands sent to the instrument. For example, to send a command to the HP3325B Function Generator to set the amplitude to 5 volts, you would enter the command string "AM 5 VO".

This exercise uses the HP 3325B function generator configured in the previous section. If necessary, go back to “Using Direct I/O"and configure the instrument before you continue.

1 In the fgen(@(NOT LIVE))object, double-click the transaction bar to get the I/O Transaction dialog box, as shown below.

The down arrow next to WRITE shows a menu of transactions: READ, WRITE, EXECUTE, and WAIT. To write data to an instrument, use the default selection. Open the object menu and consult Help to find out about each action.

2 Use the default selections WRITE, TEXT, DEFAULT FORMAT, and EOL ON. Click the input field labeled a, type "AM 5 VO" (including the quotes), and click OK.

You should see the transaction WRITE TEXT "AM 5 VO" EOL as shown below. The text in quotation marks is the command that will be sent to the HP3325B when the program runs.

In most cases, the process will be the same for sending text commands to instruments. However, there are instruments that specify characters sent at the end of each command or at the end of a group of commands. You need to get this information from the instrument documentation, then include it in the Direct I/O Configuration dialog box.

Sending an Expression List to an Instrument

In some cases, you may want to send an expression list to an instrument. For example, you may want to loop through a number of frequencies in the Function Generator. To do so using a Direct I/O Transaction, you would use a variable for the frequency in an expression list, and add a data input for that variable to the Direct I/O object. The following steps describe how to send an expression list to an instrument.

1 Place a second Direct I/O object for the HP3325B in the Main window. Double-click in the transaction area to get the I/O Transaction dialog box.

You can use all of the defaults except for the command string. In this case, use the format "FR", <frequency>, "HZ". This is an Expression List, each expression being separated by commas. The frequency is represented by variable A, which will be a data input to the Direct I/O object.

2 Click on the input field for command strings and type "FR",A,"HZ". (For example, if A were 100, VEE would send the string "FR100HZ".) Click OK. Notice that VEE automatically adds a data input pin labeled A.

3 Select Flow [image] Repeat [image] For Range and place it to the left of the Direct I/O object.

4 Connect the For Range data output pin to the Direct I/O data input pin.

5 Edit the fields in For Range to: From 10, Thru 1.8M, and Step 50k.

For Range will now send out numbers ranging from 10 to 1.8 million in steps of 50,000. As the numbers are received by the Direct I/O object, the command string causes the function generator to output the frequencies. The Direct I/O setup should look like below.

6 (Optional) Connect an HP3325B to your computer, if you have one, and edit the configuration of this Direct I/O object to include the address of the instrument. Run the program and you will see the instrument generating these frequencies.

Reading Data From an Instrument

Instruments send data to a computer in many different formats. To read data from an instrument, you must know the datatype you want to read, and whether the data is returned as a single value (scalar) or an array. You must also know if the instrument returns data as text (ASCII) or binary.

You can find this information in the instrument documentation, or you can use the Agilent IO Monitor in the I/O menu to examine the data being returned. This information determines how to configure the I/O transaction.

In this example, an HP3478A Multimeter is connected to the HP3325B Function Generator described in the last exercise. When the generator sends out a certain frequency, the multimeter triggers a reading and sends the results back to VEE. The following steps describe how to configure the transactions for the multimeter.

note

This example describes a READ TEXT transaction. Other choices for READ include BINARY, BINBLOCK, and CONTAINER, which are discussed in detail in Using the Direct I/O Object and READ Transactions

1 Select I/O [image] Instrument Manager.... Click Add.... Change the name to dvm. Click on Advanced... and set Live Mode: to OFF. Assuming that you do not have an HP3478A connected, click OK to return to the Instrument Manager. (If you do have an HP3478A, modify the address and the instrument will track the commands.)

2 Highlight dvm(@(NOT LIVE)) and click Direct I/O under Create I/O Object.

3 Double-click the <Double-Click to Add Transaction> bar to display the I/O Transaction dialog box.

4 Highlight the input field and type "T5", then click OK. This will write the "T" command to the instrument. T5 is the command for a single trigger to the multimeter.

5 Open the object menu and click Add Trans... to add another transaction bar, or use <Double-Click to Add Transaction> to add a transaction and display the I/O Transaction dialog box.

6 Click the down arrow beside WRITE to get a drop-down menu, then select READ. When you select READ, new buttons appear in the I/O Transaction box.

7 Check the ExpressionList input field to verify that it contains an x. Press Tab to move to the next field. Data returned from an instrument is sent to data output pins. In this case, data will be read from the instrument and put into a data output named x.

note

Names are not case sensitive.

8 Leave the REAL64 FORMAT default. The multimeter returns single readings as real numbers.

9 Leave DEFAULT NUM CHARS as is.

The default for the number of characters is 20. If you want to change the number, click on DEFAULT NUM CHARS to toggle to MAX NUM CHARS and change the number 20 to the desired number.

10 Leave SCALAR as is and click OK.

You will see the transaction displayed on the bar as READ TEXT X REAL64. Notice that VEE automatically adds a data output named x.

note

If the instrument is returning an array of values, click on the SCALAR menu in the I/O Transaction dialog box to get the menu for different dimensions, as shown in below. Once you have selected the array dimension, you also need to specify a size for the array.

11 Add a Display [image] AlphaNumeric to the right and connect its input to the Direct I/O output labeled x.

The two Direct I/O transactions should look like :

The process to configure a transaction is similar, regardless of the data format for the READ TEXT transaction. You can explore the other formats available. For a more detailed information refer to Using the Direct I/O Object and READ Transactions

To create a complete test program, this multimeter object and a function generator object could be combined with VEE data and display objects. Fully functional test programs are easy to create in VEE.

Uploading and Downloading Instrument States

Some instruments offer a “learn string” capability. The learn string embodies all the function settings that compose an instrument state. Direct I/O will upload this learn string, save it with that particular Direct I/O object, and later allow you to download it to the instrument in the program. To upload an instrument state, follow these steps:

1 Set the instrument to the desired state manually.

2 Open the Direct I/O object menu and click Upload State.

Now this state is associated with this particular instance of the Direct I/O object.

3 Open an I/O Transaction dialog box by double-clicking in the transaction area.

4 Click TEXT, select STATE (LEARN STRING), then click OK to close the I/O Transaction box. The previously captured state is sent to the instrument when this WRITE transaction is executed.

Uploading and downloading are controlled by the settings in the Direct I/O Configuration dialog box. If Conformance is IEEE 488.2, then VEE will automatically handle learn strings using the 488.2 *LRN? definition. If Conformance is IEEE 488, then Upload String specifies the command used to query the state, and Download String specifies the command that precedes the state string when downloaded. The following figure shows an example.

Conformance can support IEEE 488 or IEEE 488.2. This example uses the HP 54100A Digitizing Oscilloscope, which conforms to IEEE 488 and requires a "SETUP?" to query the learn string and "SETUP" to precede the learn string when downloading. When you select Configured for State (Learn String) two more fields appear, labeled Upload String and Download String. The proper strings have been entered in their input fields.

See Also

To Use a Direct I/O Object

Direct I/O

I/O Configuration Techniques


Lab 3-4: Configuring a VXIplug&play Driver

Lab 3-4: Using a VXIplug&play Driver

VXIplug&play drivers are issued and supported by the various instrument vendors. These are C-based drivers and are designed for the maximum performance and ease of use.

Agilent VEE is fully VXIplug&play compatible. All available VXIplug&play drivers from Agilent Technologies ship as a separate product, and are also available on the Web at http://www.agilent.com/find/inst_drivers and on the Agilent Developers Network (ADN) at http://www.agilent.com/find/adn. These same drivers are also included with VEE along with all Agilent Technologies panel drivers. To get VXIplug&play drivers for other instruments, contact the instrument vendor.

Configuring a VXIplug&play Driver

This example describes how to configure an hpe1412 driver.

1 Select I/O [image] Instrument Manager....

2 Highlight My configuration, then click Add... under Instrument to get the Instrument Properties dialog box. Enter a name, such as Instrument, and click Advanced... to display the Advanced Instrument Properties dialog box.

3 In the Advanced Instrument Properties dialog box, toggle Live Mode: to OFF and select the Plug&play Driver folder. Click the Plug&play Driver Name: field to display the drop-down menu which lists all the drivers installed on the computer. This example uses the hpe1412 driver, as shown below..

Select the hpe1412 driver, click OK to return to the Instrument Properties dialog box, and click OK to return to the Instrument Manager. There should now be an entry for Instrument(@(NOT LIVE)).

4 Highlight Instrument(@(NOT LIVE)), and under Create I/O Object, select Plug&play Driver. Click to place the object.

note

In VEE, a VXIplug&play driver resembles a Direct I/O object.

To make measurements with the instrument, you need to configure I/O transactions that use C functions in the VXIplug&play driver. The driver provides you with panels to pick the right functions to use.

5 Double-click on the transaction bar labeled <Double-click to Add Function>, and Select a Function Panel is displayed.

note

VEE automatically initializes the instrument. You do not have to use an init function, as you would in other languages.

The next figure shows the hierarchy of functions in the function panel. Notice that Help for the item selected is displayed in the dialog box.

6 Click Configure Present Settings [image] Measurement Type [image] Measurement Type Setup. The Edit Function Panel is displayed. Under func, click to display the drop-down list. Select the default DC Voltage,.

7 Click OK. The To/From Instrument object now contains an entry for hpe1412_configure(instruHandle,hpe1412_CONF_VOLT_DC).

8 In the To/From Instrument object, double-click to add a function and select Take Measurement under Measure. Click on the Configuration folder to display the dialog box.

9 Click OK. A second function call is listed in the To/From Instrument object.


Lab 5-1: Creating an Array for Test Results

The easiest way to create an array is to use the Collector object.

This exercise uses the For Count object to simulate four readings from an instrument. The readings are put into an array and the results are printed. The principles will be the same regardless of the data type or the size of the array, since the Collector will take any data type and create the array size automatically depending on the number of elements sent.

1 Select Flow [image] Repeat [image] For Count, Data [image] Collector, and Display [image] AlphaNumeric.

Object Name

Description

about the

For Count object

For Count outputs increasing integer values starting at 0 depending on the number of iterations you specify in the input field. Highlight the default number 10 by double-clicking, then type 4. For Count will output 0, 1, 2, and 3.

about the Collector object

The Collector receives data values through its Data input terminal. When you finish collecting data, you “ping” the XEQ terminal to tell the Collector to construct the array and output it. You can use the For Count sequence output pin to ping the Collector XEQ pin. The Collector displays a button that toggles between a 1 Dim Array and n+1 Dim Array.

Double-click the Collector to get the open view, and read through Help in the object menu to understand the object.

2 Click n+1 Dim in the Collector to change the selection to 1 Dim Array.

3 Connect the For Count data output pin to the Data input pin on the Collector.

4 Connect the For Count sequence output pin to the XEQ input pin on the Collector.

The XEQ pin, a special trigger pin that exists on several different objects, determines when the object executes. In this case, you want the object to fire after all of the data for the array has been collected.

5 Connect the Collector data output pin to the AlphaNumeric data input pin.

6 Enlarge AlphaNumeric to accommodate the array by clicking and dragging on any corner of the object. (You could also have enlarged AlphaNumeric when you first selected it by using “click and drag” on the object outline.)

7 Run the program. It should look like follows.

See Also

Store Test Results Using Arrays


Lab 5-2: Extracting Values from an Array

To extract values from an array, you can either use the bracket notation in an expression, or use the Access Array [image] Get Values object. The following example uses expressions in the Formula object. You will add several objects to the program in this exercise.

1 Delete the data line between the Collector and AlphaNumeric by placing the mouse pointer over the line, pressing Shift-Ctrl, and then clicking the left mouse button. Then iconize the Collector.

2 Select Device [image] Formula and clone it. Move AlphaNumeric to the right, and put both Formula objects to the right of the Collector.

3 Connect the Collector data output to the data inputs of the Formula objects. Enter A[2] in the upper Formula input field, and A[1:3] in the lower Formula input field.

4 A[2] will extract the third element of the array as a Scalar; A[1:3] will return a sub-array of three elements holding the second, third, and fourth elements of A (meaning the array on the A input terminal).

5 Clone AlphaNumeric and connect a display to each Formula object.

6 Run the program. It should look like as follows.

See Also

Store Test Results Using Arrays


Lab 5-3: Using the To/From File Objects

This lab exercise describes the process of getting test data to and from files. In this exercise, you will store and retrieve three common test result items: a test name, a time stamp, and a one-dimensional array of Real values. The same process will apply to all VEE data types.

Sending a Text String to a File

1 Select I/O [image] To [image] File. Set the entries as follows

Operation | Description
filename | Use the default file myFile. The default file can be changed by clicking the To File input field to get a list box of files in the home directory.
Clear File At PreRun & Open | Check this box. By default, VEE appends new data to the end of an existing file. Checking the box clears the file before new data is written.

2 Double-click in the transaction area to display the I/O Transaction dialog box. (Refer to I/O Transactions, if necessary.)

WRITE TEXT an EOL is the default transaction. It writes the data on pin a using TEXT encoding and a specified end-of-line sequence. VEE is not case-sensitive. You can use lower-case or upper-case strings for data input and data output terminal names.

Set the entries as follows:

Entry | Description
a (expression field) | The expression list field is highlighted and contains the default a. Type "Test1", then click OK. (You need the quotation marks to indicate a Text string. If you typed Test1 without the quotation marks, VEE would interpret this as a terminal name or global variable name.)
WRITE | Use the default WRITE.
TEXT | Use the default TEXT. The encoding TEXT will send the data using ASCII characters.
DEFAULT FORMAT | Use DEFAULT FORMAT. The DEFAULT FORMAT will choose an appropriate VEE format such as STRING.
EOL ON | Use the default. The default EOL sequence is the escape character for a new line \n.

3 Click OK to return to the To File object. The transaction bar should now contain the statement WRITE TEXT "Test1" EOL. This transaction sends the string Test1 to the specified file.

Sending a Time Stamp to a File

The function now() in the Device [image] Function & Object Browser [image] Time & Date category gives the current time expressed as a Real64 Scalar. The value of the Real is the number of seconds since 00:00 hours on Jan. 1, 0001 AD.

Therefore, now() returns a value about 63G. VEE provides this format because it is easier to manipulate mathematically and conserves storage space. If you want to store the time stamp in a more readable format, use the TIME STAMP FORMAT in the To File object. Follow these steps to send a time stamp to a file.

1 In the same To File object, double-click in the transaction area to display the I/O Transaction box.

2 Double-click the expression list input field to highlight the a and type now(). The now() function sends the current time from the computer clock in a Real format.

3 Change the Real format to the Time Stamp Format. Click the arrow next to DEFAULT FORMAT to display the drop-down menu and select TIME STAMP FORMAT. The I/O Transaction dialog box now displays additional entries. Set the entries as follows:

Time Stamps | Description
Date & Time | Select Time in the drop-down menu.
HH:MM:SS | Click and toggle to HH:MM (from the hour, minute, and second format to the hour, minute format).
24 HOUR | Click and toggle to 12 HOUR (from 24-hour format to a.m. and p.m. format).

The I/O Transaction dialog box should now look like Follows.

4 Click OK to return to the To File box. The second transaction bar should now contain the statement WRITE TEXT now() TIME:HM:H12 EOL.

Sending a Real Array to a File

Create a one-dimensional array of four elements using the For Count and Collector objects, and append it to myFile.

1 Select Flow [image] Repeat [image] For Count. Change the default value in For Count to 4.

2 Select Data [image] Collector. Double-click the Collector to switch to Open view. Connect the data output of For Count to the data input of the Collector (the top input pin). Connect the For Count sequence output pin to the XEQ pin (the bottom input pin) on the Collector. Iconize the Collector.

3 The Collector will now create the array [0, 1, 2, 3], which you can send to the data file.

4 Using the same To File object, double-click in the transaction area. In the I/O Transaction dialog box, open the DEFAULT FORMAT menu, and select REAL64 FORMAT.

5 The I/O Transaction dialog box displays additional buttons for the REAL64 FORMAT selection. You can leave all of the default choices, but you might want to investigate the options for future reference.

6 Click OK to close the I/O Transaction box. The transaction bar in the To File object should now contain the statement WRITE TEXT a REAL64 STD EOL. Notice that VEE also automatically adds an input terminal a.

7 Connect the output from the Collector to the input a of To File. The program should now look like follows. (The configured I/O Transaction box is also displayed.)

Retrieving Data with the From File Object

To retrieve data using a From File object, you must know how the data was stored.

note

You can also store and retrieve data using To DataSet or From DataSet, which does not require you to know the type of data in the file. Datasets are described in the section Lab 5-5: Using DataSets

In this example, the name of a test is stored in a String Format, followed by a time stamp in Time Stamp Format and an array of Real64 numbers. You will create three transactions in From File to read the data back into VEE.

1 Select I/O [image] From [image] File and place it below the To File object.

2 Connect the sequence output pin of the To File object to the sequence input pin of the From File object.

This sequence connection ensures the To File object has completed sending data to myFile before From File begins to extract data.

3 In the From File object, leave the default data file myFile. Double-click the transaction bar to get the I/O Transaction dialog box. Click REAL64 FORMAT and change it to STRING FORMAT, as shown follows.

4 All of the other defaults are correct, so click OK to close the I/O Transaction box. The transaction bar in the From File object should now contain the statement READ TEXT x STR.

Now add two more transactions to read back the time stamp and the real array.

5 In the same From File object, double-click below the first transaction bar. The I/O Transaction dialog box appears. Double-click on the expression list input field to highlight x and type y, for the second transaction to read data back to pin y. (If this pin were left as “x” then the second transaction would overwrite the data that the first transaction put into “x,” instead of appending it.) Change REAL64 FORMAT to STRING FORMAT, then click OK.

note

To read the time stamp back as a text string, use the STRING FORMAT. The TIME STAMP FORMAT converts the time stamp data back to a Real number.

6 In the same From File object, double-click below the second transaction bar to display to the I/O Transaction dialog box. Set entries as follows:

Entry | Description
(expression field) | Edit x to z, so that the Real array is read back to the Z output terminal.
SCALAR | Change SCALAR to ARRAY 1D.
SIZE: | Now the I/O Transaction box adds a SIZE button. In this case, the array has four elements. Replace 10 with 4 and click OK.

note

If you do not know the size of an array, you may toggle SIZE to TO END. This will read data to the end of the file without VEE knowing its exact size. For example, you could use this feature to read the entire contents of a file as a string array to examine the file contents.

The transaction bar in the From File object should now contain the statements READ TEXT y STR and READ TEXT z REAL64 ARRAY:4. Notice that VEE automatically adds the data output terminals for x, y, and z. You can also manually add or delete input and output terminals under object menu [image] Add Terminal, Delete Terminal, or using the shortcuts Ctrl-A and Ctrl-D.

7 Select Display [image] AlphaNumeric and clone it twice to get three displays. Connect the AlphaNumeric objects to the three data output pins on From File. Enlarge the array display by clicking and dragging the object by any corner.

You can also size the AlphaNumeric displays by clicking and dragging the object outlines when you first select them from the menu.

8 Run the program. It should look like follows.

Notice that the first Alphanumeric displays the title, the second displays the time of the test, and the third lists the numbers in the array.

See Also

Understanding I/O Transactions, I/O Transaction Format


Lab 5-4: Using Records

This exercise describes how to use the Record datatype. You will learn how to build a record, how to retrieve a particular field in that record, how to set a chosen field, and how to unbuild the entire record in a single step. This exercise also uses the time stamp function now() in a different way.

Building a Record

Build a Record with three fields: the name of a test stored as a String, a time stamp stored as a Real Scalar, and simulated test results stored as a four element Array of Reals. When you retrieve these fields in the next exercise, you will see that you can convert the time stamp into a number of different formats for display.

Create the test name by selecting Data [image] Constant [image] Text and entering Test1 in the input field. Rename the object Text Constant. Iconize Text Constant.

9 Select Device [image] Function & Object Browser. Click Built-in Functions => Time & Date => now, and click Create Formula. Place the object below Text Constant.

10 Select Data [image] Constant [image] Real64 and place it below now().

11 You can turn this Scalar Real64 into an Array 1D by clicking Properties... in the Real64 object menu and choosing 1D Array.

12 Open the Constant Properties box by double-clicking on the Real64 title bar. Select 1D Array under Configuration, change the Size to 4, then click OK.

Enter four values into this array by double-clicking next to element 0000 to highlight the first entry, then input the values 2.2, 3.3, 4.4, 5.5 using the Tab key between each entry. Iconize Real64.

13 Select Data [image] Build Data [image] Record and place it to the right of the three other objects. Add a third data input terminal so you can input three fields. Open each terminal by double-clicking over the terminal and rename the three input terminals to testname, time, and data.

The Output Shape on the Build Record object toggles between Scalar and Array. The Scalar default will be the correct choice for the majority of situations.

14 Connect the Text Constant object to the testname terminal, the now() object to the time terminal, and the Real64 object to the data terminal on the Build Record object.

15 Run the program. Double-click on the Record data output terminal to examine the record. It should look like follows.

You can see the three fields and their values. If you click on the Real64: Array 1D button, a list box shows the actual values. Notice that the time stamp has been stored as a Real64 Scalar. In the next exercise, you will convert it to a more readable form. Click OK to close the Output Terminal Information dialog box. Save the program as records.vee.

Getting a Field From a Record

Use the Get Field object to extract each of the three fields from the record, then display the values for each.

1 Open the records.vee program.

2 Select Data [image] Access Record [image] Get Field. The object appears with rec.field for a title.

The data input labeled rec will take any record regardless of the number and type of fields. Rec.field is the default selection in the input field, but this can edited to retrieve any field. Rec refers to the record at the data input terminal by the same name. (Remember that VEE is not case sensitive.)

note

The Get Field object is a Formula configured with inputs and an expression, like the formulas in the Function & Object Browser.

3 Clone rec.field twice and place the objects to the right of Build Record.

4 Connect Build Record data output to all three rec.field objects.

5 Since the three fields are stored as testname, time, and data, you will have to edit the rec.field objects to get the appropriate field.

6 Edit the three rec.field object expression fields to rec.testname, rec.time, and rec.data.

7 Select Display [image] AlphaNumeric and clone it twice. Connect the three displays to the three rec.field objects. Resize the third display to accommodate the real array, about three times longer than the other objects.

8 Open the second AlphaNumeric display object menu and select Properties, then select the Number folder. Click to the left of Global Format to remove the check mark.

Set the display format. Open the Standard menu in the Real section. Select Time Stamp and click OK.

9 Click HH:MM:SS to toggle to HH:MM. Click 24 HOUR to toggle to 12 HOUR.

10 Run the program and save it as getfield.vee. The program should look like follows.

Notice that the second display lists the weekday, the date, and the time expressed in hours, minutes, and an a.m. or p.m. designation.

Setting a Field in a Record

This exercise shows how to change data in specific fields of a record.

note

You can re-use the same Record with different tests.

1 Open the getfield.vee program.

2 Delete all objects after Build Record, by selecting objects and pressing Ctrl-X.

1 Select Data [image] Access Record [image] Set Field and place it to the right of Build Record. Connect the output from Build Record to the rec input of Set Field. The title will be rec.field = b.

Set Field works by assigning the expression on the right side of the assignment symbol (=) to the left hand side. Therefore, the specified field of rec is modified to contain the value(s) from the right hand side. The rest of the record is unchanged. You connect the incoming record to rec and the incoming new value to b. The modified record will be put on the data output terminal labeled rec.

note

The Set Field object is a Formula configured with inputs and an expression, like the formulas in the Function & Object Browser.

2 Edit the expression to rec.data[*]=b to change the value of the four element array in the data field. (You need to use the array [*] notation, because you are changing the whole array in the field of this record.) You will put the new values for the array on the input terminal b.

3 Select Data [image] Constant [image] Real64 and place it under the Build Record object. Open the object menu, and select Properties. Select 1D Array under Configuration, then edit the Size to 4, and click OK.

If the new values for the record field are contained in an array, it must have the same size as the current array.

Enter the values 1, 2, 3, 4 into Real64 by highlighting the first entry and using the Tab key to move to subsequent entries. (Do not press the Tab key after the last entry.) Connect it to the Set Field (titled rec.field=b) input labeled b.

Now use the Get Field object to extract the field rec.data from the record and display the results.

4 Select Data [image] Access Record [image] Get Field and place the object under the Set Field (rec.field=b) object. Edit the Get Field object expression from rec.field to rec.data. Connect the data output of rec.field = b to the data input of rec.field.

note

You could also use a Formula object with A.data in the expression field.

5 Select an AlphaNumeric display, size it to accommodate an array, and connect it to the rec.field output pin.

6 Run the program and save it as setfield.vee. The program should look like follows.

You can modify any Record fields as shown in this example. You could also modify part of the field. For example, try changing the expression in rec.field = b to rec.data[1]=20. Then delete the rec.field = b input b. Run the program again and you should see the array: 2.2, 20, 4.4, 5.5.

Unbuilding a Record in a Single Step

To extract all record fields and get a list of the field names and their types, use the UnBuild Record object.

1 Open the setfield.vee program. Delete all objects after Build Record.

2 Select Data [image] UnBuild Data [image] Record and place it under Build Record, switch the open view, and connect the output of Build Record to the input of UnBuild Record. Add another data output pin to UnBuild Record and rename the A, B, and C outputs to the field names: testname, time, and data.

3 Select an AlphaNumeric display and clone it four times. Connect the five displays to the five output terminals on UnBuild Record. You will have to enlarge the displays for Name List, Type List, and data to accommodate arrays. Also, reconfigure the time display to present time in day/month/year and hours, minutes using a 12 hour format.

4 Run the program and save it as unbuild.vee. It should look like follows.

Notice that the Name List pin gives the names testname, time, and data of the three fields in the record, just as the Type List identifies testname as Text, and time and data as Real64 types.

See Also

Using Records to Store Mixed Data Types


Lab 5-5: Using DataSets

A DataSet is simply an array of Records stored in a file. This exercise shows how to get data into and out of a DataSet.

Storing and Retrieving a Record from a DataSet

This exercise creates an array of ten Records, each containing three fields with a test name, a Real64 Scalar, and an array of Reals. It stores the array of Records in a DataSet, and retrieves the records and displays them.

1 Select Flow [image] Start. Select Flow [image] Repeat [image] For Count and place the object under Start. Select Device [image] Formula and place the object to the right of For Count. Connect Start to the sequence input pin on For Count; connect the For Count data output pin to Formula data input pin.

2 Double-click the Formula expression field to highlight the default expression, and then type “test“ + a.

When you click Start, the For Count object outputs integers zero through nine sequentially to the A pin of Formula. In the Formula object, the integers are added to the word “test” and output as Text Scalars: test0, test1, test2,...,test9. These values will fill the first fields in the ten Records.

3 Select Data [image] Build Data [image] Record, and place the object to the right of Formula. Add a data input pin. Connect the data output of Formula to the A input of Build Record.

4 Select the Function & Object Browser icon from the tool bar.

a Choose Built-in Functions, Probability & Statistics, and random to create the random (low, high) object. Place the object below the Formula object.

b Delete the input terminals, and change the input parameters from low to 0, and from high to 1.

c Rename the object Random Number, and connect its data output to the B terminal of Build Record.

5 Connect the Formula sequence output pin to the sequence input pin of Random Number. Connecting the sequence pins ensures that each iteration of the program puts a new random number into the B field of the particular record.

6 Select Data [image] Constant [image] Real64. Place the Real64 object below the Formula object.

a Open the object menu and click Properties. Type Real Array for the title, under Configuration click 1D Array, and change the Size to 3. Click OK.

b Highlight each entry in the array by double-clicking and typing in the numbers 1, 2, and 3.

c Connect the Real Array data output to the C terminal on Build Record.

7 Select I/O [image] To [image] DataSet and place the object under Build Record. Connect the data output of Build Record to its data input. Leave the default file name myfile, and check Clear File At PreRun.

8 Run the program. It should put an array of ten records into the DataSet called myFile, as shown follows.

Now retrieve the array of records and display it using the From DataSet and Record Constant objects.

9 Select I/O [image] From [image] DataSet and place the object below For Count. Leave the default file name, myFile. Click the Get Records field to toggle from One to All. Finally, leave the default of 1 in the expression field at the bottom.

With these settings, VEE looks at the DataSet in myFile and finds all the records that fit the criterion in the expression field. If you set Get Records to One, VEE would output the first record that met the criterion in the expression field. The 1 signifies a TRUE condition meaning that all of the records fit the criterion, so the entire array of records in the file will be put on the output pin labeled Rec. Other uses of the expression field are explained in other exercises. Consult Help in the object menu for more information.

Connect the For Count sequence output pin to the sequence input on the From Data Set object. This ensures the part of the program that sends data to myFile executes before the data is read from the file. You can turn on Show Data Flow to show the order of events.

10 Select Data [image] Constant [image] Record and place the object below To Data Set. Open the object menu and select Add Terminal [image] Control Input. Click Default Value from the list box presented, then click OK. Resize the Record object to be larger, so you can see the results when you run the program.

The record received will become the default value. In this case, Record will receive an array of records from the From Data Set object, and it will format itself to display that array of records.

11 Connect the From Data Set output pin Rec to the Default Value pin on Record. If you would like to see this terminal, open the object menu and select Properties, then Show Terminals, then OK. A dotted line appears between From Data Set and Record.

note

A dotted line between two objects indicates a control line.

12 Run the program and save it as dataset1.vee. The program should look like follows.

note

A From Data Set object must include at least one record that meets the criterion, or VEE issues an error message. To avoid an error, add an EOF (end-of-file) output pin to the object which activates if no records meet the criterion. You can then add actions to the program when the EOF results.

See Also

Using DataSets


Lab 5-6: Using Search and Sort Operations with DataSets

In this exercise, you will learn how to search a DataSet for information, create an operator interface for the search operation, and program a sort operation.

Performing a Search Operation With DataSets

1 Open the dataset1.vee program.

2 Double-click on the expression field at the bottom of the From Data Set object to highlight the current expression, 1. Enter Rec.B>=0.5. The object will now output all records, where field B (the random number in our code) is greater or equal to 0.5.

3 Add an EOF pin that will fire if no records match the criterion in the expression field. Place the cursor over the data output area of the From Data Set object, and press Ctrl-A. An EOF output pin is added to the From Data Set object.

note

To add an EOF pin, you could also open the object menu, and click Add Terminal [image] Data Output....

4 Run the program and save it as dataset2.vee.

Creating an Operator Interface for a Search Operation

This exercise adds a menu for an operator to extract data from the test results database. The operator interface is secured to avoid accidental modifications to the program.

The specifications of the program are as follows:

• Provide a test menu that will allow operators to select a particular test from test0 through test9, from which they want all related test data.

• Display the specified test results with the fields and values labeled. The operator should be able to interact with the display to gain more detailed information.

• Include clear operating instructions.

Follow these steps to create the program.

1 Open the dataset2.vee program.

Add a control input that will allow you to input the expression in the From Data Set object programmatically.

2 Open the From Data Set object menu and select Add Terminal... Control Input.... Select Formula from the menu presented. A Formula input terminal appears. Click the Get records field to toggle from All to One to access one test record at a time.

You want the user to select a particular test name. The test names are located in field A of all records. Add the expression:

Rec.A==<test name in quotation marks>

Rec.A outputs the record where field A matches the test name the operator selects. For example, if the operator selects test6, the expression should read Rec.A=="test6". The object extracts the test record, which can then be displayed.

Create a menu that allows the operator to click a button next to the desired selection.

3 Select Data [image] Selection Control [image] Radio Buttons and place the object to the left of For Count.

a Open the object menu and select Edit Enum Values.... Highlight 0000: Item 1 and type test0. Press the Tab key to move to 0001: Item2 and enter test1.When you press the Tab key after the third entry (test2), another entry automatically appears. Continue to enter values until you reach test9. Click OK and all ten entries should be displayed, from test0 to test9.

b Click the Properties selection in the object menu, change the object name from Radio Buttons to Test Menu, select Auto Execute under Execution, select Open View [image] Show Terminals, and click OK.

4 The program can now execute whenever the operator makes a menu selection, so delete the Start object. Press the right mouse button over the Start object and select Cut.

5 The program should only execute when a menu selection is made, so connect the Test Menu data output pin Enum to the For Count sequence input pin. The program should look like follows.

6 The output of the Test Menu goes into a Formula object, which then sends the correct formula to the From Data Set object.

Select Device [image] Formula, and place the object below Test Menu. (You may want to rearrange and/or resize objects as you add items during the exercise.) In the new Formula object, enter the following expression:

"Rec.A==" + "\"" + A + "\""

Element

Description

“Rec.A==”

"Rec.A==" sends a Text data type to the From Data Formula expression input. (The quotation marks indicate a text string.)

A

VEE looks at the first field A of all records in the DataSet file, and selects the first record that equals the selected test name.

“\””

The escape character for a quotation mark is \”. The escape character is then put into quotes to indicate a text string.

The test name comes from the Test Menu as an Enum data type. Quotes are required to put the correct formula into the From DataSet object.

For example, if test6 is selected, then the final formula will read Rec.A=="test6". The From Data Set object then outputs the first record it finds, whose "A" field is equal to "test6".

7 Connect the Test Menu Enum data output pin to the data input pin on the Formula object. Iconize the Formula object.

8 Connect the Formula data output pin to the control input pin on the From Data Set object labeled Formula.

9 To ensure that the old data from Formula is not reused, delete the sequence line between For Count and From Data Set. Connect the For Count sequence output pin to the Formula sequence input pin.

10 Connect the Formula sequence output pin to the From Data Set sequence input pin. This ensures the right data from Formula is being used.

11 Create a box displaying instructions for the operator. Select Display [image] Note Pad. Change the title to Test Results Database Instructions. Remove any template information that might be present. Click on the Note Pad input area and type: Select the test results you want from the Test Menu.

12 Rename the Record Constant object Test Results.

13 The program should look like follows. Run the program a few times to verify that it works. Since the Test Menu object has AutoExecute turned on, make a menu selection to run the program.

Next, create the operator interface.

14 Press Ctrl and click these objects: Test Menu, Test Results Database Instructions, and Test Results.

All objects selected show a shadow. Verify no other objects are selected.

Then select Edit [image] Add to Panel, and the operator interface appears as a panel view. You can then move and size the objects. One layout is shown below.

note

If the Add to Panel selection is grayed out, it means that you do not have any objects selected in the work area.

15 Run the program a few times by making selections in Test Menu. Save the program as database.vee.

Notice that you can get more detailed information on any given record by clicking the field names or the values in the Record Constant object (named Test Results).

note

To secure the operator interface and program from changes, select File [image] Create RunTime Version.... Enter a name for the program and VEE will automatically add a *.vxe extension to separate it from unsecured versions.

Performing a Sort Operation on a Record Field

This exercise uses the dataset2.vee program from a previous exercise. The dataset2.vee program sets a condition in the From DataSet object such as Rec.B>=0.5, and VEE extracts all the records that meet the requirement. The array of resulting records is displayed in the Record Constant object.

In this exercise, dataset2.vee is modified to sort the resulting records to determine which tests are failing by the greatest margin. The tests are sorted by the second field in descending order.

1 Open the dataset2.vee program.

2 Select Device [image] Formula and connect the From Data Set data output pin Rec to the Formula object data input pin. Double-click the Formula expression field to highlight the default formula, then enter sort(a, 1, “B”).

The Sort object is located in the Function & Object Browser, Array Category functions. You can read detailed information on its capabilities in the object menu Help entry. The sort() function is called from the Formula object.

The first parameter sorts the data on the Formula object A pin, which is in an array of records. The second parameter indicates the direction of the sort: any non-zero number indicates an ascending direction, a zero indicates descending. The default direction is ascending. The third parameter, in the case of a Record data type, indicates the name of the field to sort. Therefore, this performs an ascending sort on the B field in the array of records.

3 Select Display [image] AlphaNumeric and connect it to the data output pin of the Formula object.

4 Run the program a few times. It should look similar to follows. Notice that the program sorts all of the records returned from the DataSet file in ascending order by field B.

See Also

Using DataSets


Lab 6-1: Sending Agilent VEE Data to MS Excel

In this lab, you will generate virtual test data for MS Excel. (The example uses MS Office 2003 and the MS Excel 11.0 Object Library, and should also work with MS Office 2007/2000 and the MS Excel 12.0/9.0 Object Library.) After referencing the right Automation Type Library, you will declare some global variables of the Object type and put them in a UserFunction called globals. The global variables simplify the program and make it easier to understand.

1 Reference the Automation Library. Click Device [image] ActiveX Automation References..., select Microsoft Excel 11.0 Object Library, and click OK.

2 Create a UserFunction to store the global variables. Click Device [image] UserFunction. Rename it globals. (For more information about UserFunctions refer to the Help Contents and Index Tell me about

3 Click Data [image] Variable [image] Declare Variable and place it to the left inside globals. Change the Name to sheet. Change the Type to Object. Other items appear in the dialog box. For this exercise, you do not need to specify the Object Type and Class. (The Type and Class are specified in another example in this chapter.)

4 Clone this object three times, and rename the other objects as follows: app, range, and window. Size and move the globals UserFunction below Main. It should look like this.

5 After you have compared the entries to above figure, iconize the four objects.

Notice that by using the datatype Objects in the globals UserFunction, you could specify the Object Type and Class. There are two reasons to specify Object Type and Class: more specific type checking, and catching events.

More Specific Type Checking: For example, if you specify an Object app as being of type Excel.Application, then only an Object of type Excel.Application can be assigned to app. Assigning an Object of type Excel.worksheet or Word.bookmark will cause an error.

Catching Events: You could also use a VEE UserFunction to catch various events that could occur in the application, such as a right-button-down in the MS Excel worksheet. For any of these types of events, you can specify a VEE UserFunction to handle the event and pass information back to MS Excel.

Events are useful for ActiveX Controls, where you need a way for the control to communicate back to VEE. For more information, refer to Handling Automation Object Events.

6 Open the UserFunction globals object menu and click Generate [image] Call. This generates a Call globals object configured correctly. Place it to the left in the Main window and iconize the globals UserFunction window.

7 Click Device [image] Formula and place it in the upper center of the Main window. Rename it Set up Excel Worksheet. Connect the globals sequence out pin to the Formula sequence in pin. Delete the input terminal A from Set Up Excel Worksheet (open the Object menu and select Delete Terminal [image] Input.)

8 Inside Set up Excel Worksheet, enter the lines shown below. Notice that semicolons are used for line separators, just as in ANSI C.

Command

Description

set sheet =

The keyword set is used to assign or set whatever is on the right-hand side of the assignment operator (in this case, the equal sign) to the variable on the left-hand side of the expression. For example, set app sets the application sheet.application, which has been defined as an Excel worksheet.

CreateObject
(“Excel.Sheet”).

Creates a new instance of the Automation Server (in this case, MS Excel) and creates an empty sheet (Excel terminology for a new workbook). Each Automation Server has its own terminology, but the syntax is the same. For example, to create a report in MS Word, you would enter CreateObject(“Word.Document”) to run Word and create a blank document.

If the set keyword is used, the right-hand side object pointer itself is assigned to the left-hand side variable. If set is not used, then the default property (often the name) of the right-hand side is assigned to the left-hand side. For more information, refer to Manipulating Automation Objects.

worksheets(1);

Now that Excel is running with a new workbook in it, with CreateObject("Excel.Sheet"), you want to address the first worksheet in it. Add worksheets(1) to the statement, so the entire statement reads:

set sheet = CreateObject("Excel.Sheet").worksheets(1);

This sets sheet to Sheet 1 of the report. (To see an example, open MS Excel and select File => New to create a new workbook. You will notice there are several sheets in it labeled Sheet1, Sheet2, and so on. You want Sheet1.)

set app = sheet.application;

Asks Excel for a pointer to the entire application, and not just the worksheet itself, by asking the worksheet for its property Application and setting it to the variable app.

app.visible = true;

Sets the app’s visible property to true in order to display Excel on screen (so that you can see it).

set window = app.windows(1);

References the first window.

window.caption = “Test System Results”;

Sets the first window’s caption to “Test System Results.”

note

For more information about the Application Server libraries, refer to the many books available about ActiveX Automation and MS Visual Basic. You can probably find information on the World Wide Web about ordering books such as Office 2003 or the Office 97 Visual Basic Programmer’s Guide. The books will help you with VEE as well, since VEE syntax is very similar to MS Visual Basic.

9 Create a Formula object (under Device [image] Formula). Clone the Formula object to create a second Formula object. Create a For Range object (under Flow [image] Repeat [image] For Range). Rename the objects, connect them, and configure them as follows. (Be sure to delete the input terminal on the Formula object Fill in Title.)

The instructions in the Formula objects and the For Range object are described as follows:

Formula | Description
sheet.cells(1,1) = “DC Volts” | Refers to the first row and column in the Excel worksheet. The text DC Volts will be placed there. This sets the default property (which is value) of cell (1,1), to "DC Volts".
sheet.cells(A+1,1) = random(1,100) | This statement is shorthand for sheet.cells(A+1,1).value=random(1,100). The worksheet cell at row A+1, col 1 gets the row number by adding 1 to the input pin A value but stays in column 1. The value between 1 and 100 returned by random is assigned to the specified cell in the worksheet.
from 1 thru 20, step 1 (the For Range object) | As the For Range object outputs the integers from 1 to 20, Fill in Cells puts the random number in the specified cell.

10 Create a Formula object and an AlphaNumeric object, rename, configure, and connect them as follows.

The entries in the Formula object are as follows:

Entry | Description
set range = sheet.range(“A2:A21"); | Sets the VEE variable range to reference the range A2 to A21 on the Excel worksheet. (A refers to the first column in a worksheet.)
range.NumberFormat = “##,#00.00"; | Assigns the format to each of those cells with the pound signs (#) allowing for larger numbers, if necessary.
app.worksheetFunction.average(range); | Calls an Excel method average() that returns the average value of the designated range of values, which is displayed in Results Average.

11 Save the program as results_average.vee. Run the program. MS Excel will launch with a worksheet like the one follows.


Lab 6-2: Creating an Agilent VEE to MS Excel Template

1 Open results_average.vee.

2 Change the For Range object to loop 10 times.

3 Add the input B to Fill in Cells and change the statement inside to read: sheet.cells(A+1,1) = B[A-1].

4 Click Device [image] Formula, rename it to Array of Test Data, and enter the embedded functions randomize(ramp(20), 4.5, 5.5) to create a random array of 20 elements with values from 4.5 to 5.5. Delete the input pin and connect the data output pin to the B input of Fill in Cells.

5 Change the range in the Formula box on the bottom of the screen from A21 to A11. The statement should now read:
set range = sheet.range(“A2:A11");

6 Save the program as report_template.vee and run it. Compare it to the Excel worksheet and the complete program as shown below.

You can re-use this program as a template for displaying test results in MS Excel. You simply put the test data into arrays and modify the rest of the template to fill in the appropriate cells in the right format.

To find additional methods and properties in the MS Excel library, look at the Function & Object Browser and choose the ActiveX Objects and Excel. You can choose a Class or Member and press Help to get Help provided by the Automation Server author (in this case, Microsoft). For more complete information about these libraries, consult Microsoft documentation.

On Your Own

Generate a waveform and strip out the Time Span to get an array. Create a VEE object for MS Excel with a worksheet and set it to an Object variable. Make the application visible. Then put the 256 point array into the worksheet range "A1:A256" in one step, instead of one cell at a time.

Use an Unbuild Waveform object. Use the [a] build array syntax to create a 2D array from a 1D array. Then call the function transpose() to make it a 256 x 1 array instead of a 1 x 256 array for Excel to accept it in one step, as shown below.

Extending Capabilities With MS Excel

Following figure shows a more elaborate example of a program to display test results in MS Excel. You can see how knowledge of a few more calls in the MS Excel library can expand the template for displaying VEE data in MS Excel.

The entries are shown as follows:

Item | Description
MS Excel Window Size | Notice the Drop-Down List in the upper right work area. This allows you to choose one of three options xlMaximized, xlMinimized, xlNormal to select the size of the worksheet window inside Excel when it comes up. Each window size is associated with a number, which VEE calculates and puts in the wndState variable. This value is then assigned to the windowState property in the Excel library.
Memory Tracking | (Click Show Terminals in the Properties boxes on the Formula and Meter objects.) Notice the memoryTotal and memoryUsed properties in the Excel library that are assigned to the VEE variables memTotal and memUsed. These values are then used to calculate the ranges to configure a VEE meter before it displays the memory being used by MS Excel.
Number Format | Notice how easy it is to add a dollar sign to the number format.
sheet.SaveAs (filename) | The SaveAs() method is being called from the Excel library to automatically save the worksheet. Notice that a File Name Selection box (from the Data Þ Dialog Box menu) is used to display the pop-up Save As box from VEE. The file name you select is then used as a parameter in the Excel SaveAs() method call.
Press to Kill Excel | The Confirm (OK) button has been used to signal when you want to close Excel.
Close Excel | The quit() method is called to tell MS Excel to exit.


Lab 6-3: Using MS Word for Agilent VEE Reports

To begin, follow the steps to declare five variables as type Object.

1 Click Device [image] ActiveX Automation References... and select Microsoft Word 11.0 Object Library.

2 Click Data [image] Variable [image] Declare Variable.

a Change the Type field to Object. Clone it four times.

b Name the five object variables App, Doc, Wnd, Sel, and Bmp.

c Select Specify Object Type on all of them. The advantages of declaring the particular Class within a Library are as follows: VEE can do type checking for program errors, and you can catch events from the Automation Server.

d Then click the Edit... button and select Word for Library in each case. Select the following Classes:

App will use Application

Sel will use Selection

Wnd will use Window

Doc will use Document

Bmp will use Shape

e Select Enable Events where the class permits it. Iconize these five icons. See follows for the open view of these variables.

3 Create a UserFunction called Graph, which uses a Function Generator virtual source to send a sine wave to a Waveform (Time) display. Create a panel view of the display only. Then generate a Call Graph object in the Main window. (Recall that the UserFunction object menu includes an easy way to generate a call.)

Now create a bitmap file of the Panel with the Waveform display to use in the report in MS Word.

4 To create a file name for the bitmap, click Device [image] Formula. Rename it Image Filename. Enter installDir() + "\\panel.bmp" in the Formula input field. (Use the escape sequence \\ to specify the ASCII character \.) Delete input terminal A.

If you installed in c:\Program Files\Agilent\ for example, you would then generate the following text string on the Result output pin:
C:\Program Files\Agilent\VEE Pro 8.5\panel.bmp.

5 Create another Formula object and enter
savePanelImage("Graph", FileName, 256). Rename the input terminal to FileName.

6 This saves the screen dump from the UserFunction Graph in the panel.bmp file in the installation directory at a color depth per pixel of 256.

7 Create another Formula object and enter the statement:
Set App = CreateObject("Word.Application")
This launches MS Word and assigns the object variable app to refer to this instance of the application. Delete input terminal A. Connect Call Graph, ImageFileName, and savePanelImage as follows.

8 Click Device [image] Formula and enter the statements shown in the following figure, which are also described below. Rename input terminal A to FileName. Connect the data input and sequence input pins as shown in the following figure.

In above figure, notice that you can nest property and method calls together with the Object’s dot notation. Refer to ActiveX documentation to find the right properties in the target applications. You can use the properties and methods described here to begin generating test and measurement reports. The entries in the Formula object are:

Entry

Description

App.Visible = 1;

Makes MS Word visible on the screen.

Set Doc = App.Documents.
Add();

Adds a Document in MS Word and assigns it to the Object variable Doc.

Note: In the Excel example, Excel was started with a blank worksheet using CreateObject(Excel.Sheet). In this example, Word is started and the method Add() adds an empty Document to it. Either application can be created either way.

Doc.Activate();

Activates the Document above.

Set Wnd = App.Active Window;

Takes the document in the active window and assigns it to the Object variable Wnd.

Set Sel = App.Selection;

Puts focus (selection) into the document and assigns this to the Object variable Sel. This allows you to insert text.

Wnd.View.Type = 3;

Specifies the type of window for displaying the document. The 3 indicates a normal window size. A 1 would iconize the window.

Note: The 3 is used here instead of the constant wdPageView because the constant is missing from the Office 2003 Type Library.

Sel.TypeText(*** Test Results ***),
Sel.TypeParagraph();

Puts the title *** Test Results *** in the document and issue a carriage return/line feed.

Set Bmp = Doc.Shapes.
AddPicture(FileName);

Puts the panel.bmp bitmap into the document and assigns this call in the Shapes Class to the Object variable Bmp.

Sel.TypeParagraph();

Sel.InsertDateTime
(M/d/yy h:mm:ss
am/pm, 0);

Puts a time stamp in the document.

9 Add three more Formula objects and one If/Then/Else object, configure, and connect them as shown in the following figure.

The entries in the additional objects are as follows:

Object | Description
App.ActivePrinter | Requests the default printer in a string including its port.
strLen(str) != 0 | Makes sure that ActivePrinter has located a configured printer (if the string on the input is not null, then...), then outputs a 1 (=TRUE) on the Then pin, which pings the Formula object containing the PrintOut call.
DocPrintOut(0) | Prints the document.
App.Quit(0) | Closes the MS Word Application

10 Run the program. It should look like follows (If the colors look strange in the screen dump, iconize any open applications, so the PC has a full palette of colors to work with.)

For more information about controlling MS Excel and MS Word using ActiveX Automation, refer to Microsoft documentation. Remember that you can also control other Server applications that support ActiveX Automation, sometimes just called Automation, or OLE Automation.

For more information about using ActiveX controls, refer to “Using Operator Interfaces" For more information about using ActiveX from a MS Visual Basic program to control VEE, refer to The Callable VEE Active X Automation Server.


Lab 8-1: Working with Workbooks

1 Open a new VEE project.

2 Choose Excel [image] Initialize Excel Library. The VEE Excel Library functions are imported and prepared for use.

3 Choose Excel [image] New Workbook. A new Microsoft Excel workbook is created and opened. When you are creating a new workbook, it automatically becomes the active workbook. What is the “active workbook”? It is the workbook that is the focus of all operations.

4 Choose Excel [image] Save Workbook As.

5 Add a text constant and wire it to the data input terminal of the SaveWorkbookAs object. Enter C:\MyWorkbook.xls in the text constant. This step is highly recommended when working with a new workbook. This save operation is also only effective with the active workbook.

note

The active workbook or worksheet is the one that is last opened or the one that is specifically selected using the Select Workbook or Select Worksheet object.

6 Choose Excel [image] Close All Workbooks. Closes all of the workbooks whether they have been saved or not.

7 Choose Excel [image] Quit Excel. Closes the Microsoft Excel session and quits the VEE Excel Library.

Wire these objects together from sequence out to sequence in and your program should look like the following graphic:

note

The file name in the text constant includes the file extension. The VEE Excel Library is literal in its handling of file names. You must provide the full file name. You can also provide a fully qualified path if needed.

Before proceeding with this exercise, close the VEE program and create a new one.

8 Choose Excel [image] Initialize Excel Library. The VEE Excel Library functions are imported and prepared for use.

9 Choose Excel [image] Open Workbook. The following graphic shows the Open Workbook object. The last workbook that is opened automatically becomes the active workbook.

10 Choose Excel [image] Select Workbook. When you select a workbook, it becomes the active workbook. Subsequent operations are performed on the active workbook. Note the Select Workbook object requires you to input the name of the workbook, as shown in following figure. You must select it from one of the currently open workbooks or the VEE Excel Library generates an error.

note

If you select a workbook and later open or create a new workbook, the active workbook changes to the most recently opened or created one.

11 Choose Excel [image] Save Workbook. Save is only effective on the active workbook.

12 Choose Excel [image] Quit Excel. Closes the Microsoft Excel session and quits the VEE Excel Library. The Close All Workbooks step has been skipped. While this is not as graceful an exit, it is still an acceptable method.

13 Save this exercise as SelectWorkbook.vee.


Lab 8-2: Using a Workbook Enumeration

1 This exercise assumes you have a spreadsheet, MyWorkbook.xls, saved in the root directory of your C drive.

2 Beginning with the SelectWorkbook.vee program used in Lab 8-1, cut the line between Select Workbook and Call vxLib.SaveWorkbook. Create some space between these two objects.

3 Add a New Workbook object after the Select Workbook object and wire its sequence in to the sequence out of the Select Workbook.

4 Choose Excel [image] Enumerations [image] Enumerate Workbooks. Place these objects between the New Workbook object and the Save Workbook object.

5 Wire its sequence pins.

6 Run the program and you should see a result as follows.


Lab 8-3: Formatting Cells

In the following exercise you will format the borders and back color for a range of cells in an Excel worksheet.

1 Open a new VEE project.

2 Prepare the MyWorkbook.xls file by adding values to cells A1 through A4. Save and close the workbook. Exit Excel.

3 Add an Initialize Excel Library to the VEE program.

4 Add an Open Workbook object to the VEE program.

5 Add an Excel [image] Formatting [image] Format Cells object to the program and wire the sequence in to the sequence out of the Open Workbook object.

6 Open the Format Cells object and set the BackColor parameter to Gray25.

7 Add a text constant to the program, and wire its output pin to the input pin of the Format Cells object. Enter a range of A1:A4 in the text constant.

8 Add an Excel [image] Formatting [image] Auto Fit Columns object to the program and wire its sequence in pin to the sequence out pin of the Format Cells object.

9 Add a text constant object to the program, and wire its output pin to the input pin of the AutoFitColumns object. Enter a cell address of A1.

10 Add a SaveWorkbook object and wire its sequence pins as you have done previously.

11 Add a Quit Excel object and wire its sequence pins as you have done previously.

12 Run the program

13 Check the results of your changes by opening the MyWorkbook.xls and looking at the worksheet;

14 Open the Format Cells object and study the other formatting options that are available.


Lab 8-4: Using Send Record

1 Create the named range in Microsoft Excel using MyWorkbook.xls. Highlight the range of cells you want to use. Choose Insert [image] Name [image] Define to define a named range in Excel. The range is referred to in the text box at the bottom of the dialog box. At the end of the text box is an icon that switches you from name definition mode to cell selection mode.

2 Define three ranges, A, B, and Test. Make sure the named ranges do not overlap. Your record has an A field and a B field. At this point, a named range has been defined for each field in your record.

3 The Send Data [image] Record to Named Range UserFunction has an input pin and two output pins. Wire a default record constant to the input pin. Wire an alphanumeric to the upper output pin.

4 Run the program.

5 A review of the worksheet shows the A field value in the A named range, and the B field value in the B named range.

6 Note the alphanumeric object has the output “Test”. This is because the named range Test was not used by the VEE record. This feature makes it easy to discover whether your field structure is complete or if there is a naming error in Excel.

7 Save this program as SendRecord.vee.


Lab 8-5: Creating an Excel Picture from a Panel Image

1 Using the SendRecord.vee program, remove the record constant, the alphanumeric, and the CallSendRecord objects.

2 Insert an ImageSettings object from the Excel [image] Send Panel Image menu. Wire it to the outbound sequence pin of the File Name Selection object. Adjust the settings or use the defaults.

3 Add a UserFunction named UserFunction1 as follows. Note the minor modifications to the frequency and num points parameters in the Function Generator.

4 Insert the Panel Image to Picture object. Add two Text constants and two Int16 constants and wire them as follows. Wire the Panel Image to Picture as follows also. The relative size parameters allow you to size the picture up or down with 1 being 100% and .8 being 80%.

5 Put the XY Trace object on the panel.

6 Run the program and check your Excel worksheet.


Lab 8-6: Using a System Command

1 Select I/O [image] Execute Program. Click the Prog with params field to get a cursor, then type:

command.com /c dir >> c:\bob

note

Replace command.com with cmd for Windows Vista, Windows 2000, or Windows XP. If the drive letter is different from c:, then substitute that drive letter in these instructions.

(You may need to include the complete path of the command.com executable.) The command runs the DOS command interpreter, which runs the system command to display the current directory, and redirects the output (>) to the bob file instead of the computer screen.

Leave Yes for the Wait for prog exit selection. Leave Normal for Run Style, and enter c:\ for the Working directory.

2 Select I/O [image] From [image] File and place it below Execute Program. Connect the sequence out pin of Execute Program to the sequence in pin of the From File object.

Click the From File: input field labeled myFile to get a list box, enter c:\bob, then click OK. (The program creates the file bob for you.)

3 Double-click the transaction bar to get the I/O Transaction box.

a Change REAL64 FORMAT to STRING FORMAT.

b Change SCALAR to ARRAY 1D.

c Click on the SIZE: (10) field to toggle it to TO END: (*), then click OK. The transaction bar should now read: READ TEXT x STR ARRAY:* . This transaction will read the contents of the bob file.

4 Select Display [image] Logging AlphaNumeric and connect its data input pin to the From File data output.

5 Run the program. It should look like .


Lab 9-1: UserFunction Operations

This exercise describes how to create a UserFunction named ArrayStats, which will accept an array, calculate its maximum value, minimum value, mean, and standard deviation, and put the results on its output pins.

Creating a UserFunction

1 Select Device [image] Formula, delete its default input pin, and change its default expression to ramp(1024,1,1024).

This will create a 1024 element array with values from 1 to 1024.

2 Select Device [image] UserFunction. Rename it ArrayStats.

a Add one data input terminal for the array

b Add four data output terminals for the results.

c Rename the output terminals: Max, Min, Mean, and Sdev. Select max, min, mean, and sdev from the Probability & Statistics category in the Function & Object Browser box.

d Place them in ArrayStats, and connect their data inputs to A and their data outputs to the appropriate output terminals. Make the ArrayStats window smaller to see both of the Main and ArrayStats windows.

3 Iconize ArrayStats. It appears as an icon at the bottom of the workspace.

4 Click Device [image] Call, open the object menu, and click Select Function. Then click OK. Notice that VEE renames the object automatically and adds the correct pins.

5 Connect the output of Formula to the Call ArrayStats input. Select Display [image] AlphaNumeric, clone it three times, and connect the displays to the Call ArrayStats output pins. Rename the displays.

6 Run the program. It should look as follows. Save the program as array_stats.vee.

To use ArrayStats elsewhere in the program, you would click on Device [image] Call, open the Select Function box from the object menu, and choose ArrayStats. VEE would automatically rename the object Call ArrayStats, and add the necessary input and output terminals.

From the UserFunction object menu, select Generate [image] Call to bring up the Call ArrayStats object. (Make sure that the UserFunction is not expanded to the whole workspace when doing this.)

Editing a UserFunction

In this exercise, edit ArrayStats to deliver a record with four fields giving the array statistics.

1 Delete the four AlphaNumeric displays.

2 Select Edit [image] Edit UserFunction... and select ArrayStats from the Edit UserFunction list box. All of the UserFunctions in the program are displayed.

3 Open the ArrayStats object menu, click on size, and enlarge the editing window. If you need to resize objects, click and drag any corner of the object.

4 Delete the four lines going to the output terminals. (Press Ctrl-Shift and click on the line you want to delete.)

5 Select Data [image] Build Data [image] Record and place it to the right side of the ArrayStats window.

a Add two data input terminals.

b Label the four terminals after the statistical functions: max, min, mean, and sdev.

c Connect the four Formula object outputs to the inputs on Build Record.

d Rename the Max output terminal X by double-clicking Max, typing the new name, and clicking OK.

e Delete the other ArrayStats data output terminals.

f Connect the Build Record output to the X output terminal on the UserFunction editing window. The program should look like follows. Then click the iconize button on the window.

6 Open the Call ArrayStats object menu and click Configure Pinout. This will adjust the number of pins to match the recent edits.

note

In order to update the number of pins, you must open the object and click Configure Pinout whenever you change the number of inputs or outputs in a UserFunction. Or you can manually update the Call object’s input and output pins, but using Configure Pinout is much simpler. You can use Find to find all the Call objects and expressions that call a UserFunction. For more information, refer to “Finding Functions in Large Programs".

Now display a record using the Record Constant object. Use the Default Value control input to accept a record from ArrayStats. VEE automatically configures the Record Constant to hold the incoming record.

7 Select Data [image] Constant [image] Record and place it to the right of the Call Function object.

a Open the Record object menu and click Add Terminal [image] Control Input.... Select Default Value from the list box presented. You can open the Properties menu to Show Terminals, if you wish.

b Now connect the Call Function data output to the control input pin on the Record object. Notice that control lines are indicated by dashed lines to differentiate them from data lines.

8 Run the program.

Calling a UserFunction from an Expression

In this exercise, you will learn how to call ArrayStats from an expression in the Formula object.

1 Select Device [image] Formula and replace the default formula with ArrayStats(A). Click Replace in the Call ArrayStats object menu.

The Status Bar at the bottom of the VEE screen prompts you to select the replacement object. Click on the Formula object that calls the ArrayStats function. VEE automatically replaces the Call ArrayStats object with the new Formula object and retains the wiring of the data lines.

The Formula object takes the input at terminal A and sends it to the UserFunction ArrayStats. ArrayStats delivers the record of statistics to its terminal X. The first output value from the UserFunction (X) is returned to the Formula object and delivered to its Result output.

2 Run the program.

Notice that the functionality of ArrayStats in the Formula object is exactly the same as it was in the Call ArrayStats object. This example uses a Formula object, but you could call ArrayStats from any input field that accepts expressions, such as the To File object.

note

When you call a UserFunction from an expression, the UserFunction will only deliver a single output (the uppermost data output pin). If you need all of the outputs, or they cannot be put into a Record, then use the Call Function object.

note

When you call a UserFunction from an expression, input terminals are used as function parameters to pass to the function. If no data is passed to the function, you must still include empty parentheses after the function name. Otherwise, VEE assumes you are referring to a Global variable or input terminal. For example, if the UserFunction called MyFunction has no input parameters, you must write MyFunction() in an expression. The Call object does not require the parentheses, because VEE knows you are referring to a function.

Generating a Call to a UserFunction

To generate and place a call object in the Main program from a UserFunction, use the UserFunction object menu Generate menu. The Generate menu contains most of the common objects that call a UserFunction. When you select a calling object, it can be placed in the calling window, such as the Main program, properly configured with the correct name and pins.

In this exercise, you will learn how to generate the ArrayStats object in the Main program from the ArrayStats UserFunction.

1 In the same example used in above, double-click the Formula object ArrayStats to delete the object. (You could also select the object menu and select Cut.)

2 In the UserFunction ArrayStats, select the object menu and select Generate [image] Formula Call. following figure shows the Generate menu in a UserFunction object menu.

3 Place the object in Main. Notice that VEE automatically names the new object ArrayStats(A) and includes the expression ArrayStats(A) to call the UserFunction ArrayStats.

4 Connect the output from the Formula object to ArrayStats(A), and connect the output from ArrayStats(A) to Record.

5 Run the program. It should look as follows.

Open a UserFunction object menu and select the Generate menu to review the other objects that can be placed into a program to call a UserFunction. They include Call, Formula Call (used in this example), If/Then/Else Call, ShowPanel, and HidePanel objects.

UserFunctions and the Program Explorer

UserFunctions and UserObjects make VEE programs more modular and easy to understand. The Program Explorer is a valuable tool for navigating through complex programs. For example, the hierarchy of the above program is shown in the Program Explorer. To display the Program Explorer, click View [image] Program Explorer or click the Program Explorer icon on the toolbar.

Following figure shows the Program Explorer being used.


Lab 9-2: Creating and Merging a Library of UserFunctions

In this exercise, you will create a report generation program that includes a VEE library of UserFunctions. Then you will create a new program that merges the library of UserFunctions.

Creating a Library of UserFunctions

1 Create the top level program (without programming the details of the UserFunctions).

a Create four UserFunctions: BuildRecAry with one output pin, ReportHeader, ReportBody with one input pin, and ReportDisplay. Iconize all the UserFunctions.

b In Main, create four Device [image] Call objects configured and connected as follows. Save the program as Report.vee.

note

The Call object does not require parentheses when referring to a UserFunction. If you were calling the function from a Formula object, you would need to include parentheses whether or not the function used parameters.

The four UserFunctions are a library. You can see them listed by clicking Edit [image] Edit UserFunction.... Click Cancel to close the list box.

2 Program the four UserFunctions as shown in the following figures.

Following figure shows the BuildRecAry UserFunction. It includes a Formula object with the triadic expression testing if A<=5. If the expression evaluates to TRUE, then the object outputs "PASS". Otherwise, the object outputs "FAIL". (Note that the parentheses are required.)

ReportHeader UserFunction is shown below:

The next figure shows the ReportBody UserFunction. Note the array of records A[B]. As the Value of B changes from 0 to 1 to 2, you can access the particular field in that Record, including Value, Limit, and PassFail, using the <record>.<field> notation. Note that the For Count outputs start with zero. Note also that the first transaction has EOL off.

The vertical bar in quotes, "|", represents a constant string character for a vertical bar. FW:5 stands for a string field width of 5. RJ stands for right justified.

See the ReportDisplay UserFunction in detail view. Note that it reads a string array to the end of the file, specified by the asterisk sign (*) after the STR ARRAY format.

The panel view of the ReportDisplay UserFunction with Show Panel on Execute selected in the Properties box is as follows. In the Properties box, the Pop-up Panel Title has also been changed to ReportDisplay. To create the panel, select the Confirm (OK) and Logging AlphaNumeric objects, and click Edit [image] Add to Panel. Note that the Logging AlphaNumeric display has Show Title Bar deselected. Note also that Confirm (OK) button has been renamed DONE. The Confirm (OK) button is included to keep the display on the screen until the user is done viewing it.

3 Run the program and the ReportDisplay panel should pop up and display the values as shown. Click on DONE to complete execution. Then save the program as Report.vee.

Creating Another Program and Merging in the Library

In this exercise, you will create a new program and merge the library into it. This exercise builds a library of functions for generating reports. The new program contains a Note Pad object explaining each function in the library. It will be named RepGen.

You could re-use RepGen by creating new report generation UserFunctions, merging them with the program, and updating the Note Pad object to keep track of them. Then you could use the Merge Library... command to leverage all the functions from RepGen.

1 Select File [image] New.

2 Select File [image] Merge Library.... Select Report.vee from the Merge Library list box. (If you are in a different directory, type the whole file path.)

Select Edit [image] Edit UserFunction (or look at the Program Explorer) to make sure the library from Report.vee transferred to the new program. When you use the Merge Library... command, you can edit merged functions just like local functions.

3 Select Display [image] Note Pad and type the UserFunction descriptions similar to the ones shown below. Then save the program as RepGen.vee.


Lab 9-3: Importing and Deleting Libraries

Once you have created a library of UserFunctions, you may not want to merge them into every program. You might like to bring in the library at run time, use some of the functions, and then delete the library to conserve memory. The Import Library and Delete Library objects are designed for this situation.

In this exercise, you will import functions from the RepGen program. Then you will call the BuildRecAry function to simulate some test data, display it, and finally delete the library to free up memory and swap space.

1 Select File [image] New.

2 Select Device [image] Import Library and place it in Main. Set the fields in the Import Library object as follows:

Import Library Fields

Description

Library Type

The menu in the Library Type field allows you to select a UserFunction, a Compiled Function, or a Remote Function. In this case you want a UserFunction library, so leave the default.

Library Name

The Library Name shows myLib as a default. This name is used as a “handle” by the VEE program to distinguish between different libraries being imported. The Delete Library object uses this name to identify the library to be deleted. You can use the default name.

File Name

The File Name field shows a dialog box for the user program directory by default. Specify the file that holds the library of functions.

Click the default name myFile to get the list box. Select RepGen.vee (from “Lab 9-2: Creating and Merging a Library of UserFunctions"). This file will be in the directory you specified for your programs during installation.

3 Open the object menu and select Load Lib to import the library immediately instead of waiting until runtime. This command is very useful in the development stage. (In the next step, you will notice that when choosing Select Function in the Call object, the functions are designated with the library handle first, such as myLib.BuildRecAry.)

To display the library of imported functions, use the Program Explorer.

note

Because you have imported the library, you can only view the UserFunction and set breakpoints for it. You cannot edit the UserFunction. To add a UserFunction to a program that can be edited, use the Merge Library... command.

4 Select Device [image] Call and place it below the Import Library object. Connect the output sequence pin from Import Library to input sequence pin on the Call object.

5 Open the Call Function object menu and click Select Function to show a list of the functions imported with the Load Lib command. Select myLib.BuildRecAry as follows

VEE automatically inserts the function in the Function Name field and adds the required output terminal. You could also have entered myLib.BuildRecAry in the Function Name field to accomplish the same results. Use Select Function when you need to list the names of the functions in the library.

6 Select an AlphaNumeric display, enlarge it, and connect it to the Call data output.

7 Select Device [image] Delete Library and place it below the Call object. Connect the sequence pins, so the library is deleted after the BuildRecAry function has been called. You can leave the default Library Name, since this is the same name you used with the Import Library object.

8 Run the program. It should look like follows. Save the program as libraries.vee.

Note the following about names of merged and imported functions:

• If a merged function has the same name as a local function, VEE displays an error.

• If an imported function has the same name as a local function, it is allowed, but the local functions are called if only the function name is used. You can explicitly call the imported function with the MyLib_func() syntax as in the Call object in above figure.

• If two imported libraries have the same function names, the results will be indeterminate. Notice that the Call object uses the Library name myLib.BuildRecAry, so there is no confusion. Even if there were another local function or other imported function with the same name, this specifies the name and location of BuildRecAry.


Lab 9-4: Merging a Bar Chart Display Program

In this exercise, you will merge an existing program with a new program. Although the example uses a program from the VEE Lib directory, you could use any program. You will create an array with five values from 1 to 5 using the ramp() function. Instead of displaying the array with one of the internal VEE displays, you will merge the BarChart program with the program you are creating.

1 Select Formula and place it in the left work area.

2 Delete the data input terminal.

3 Change the default formula to ramp(5,1,5).

The first parameter is the number of elements desired in the ramp array. The second parameter is the starting number, and the third is the last number. For more information on this function, select Help in the Formula object menu now that it has the ramp call in it. (Or try Help [image] Contents & Index, then use the Search feature in the Index folder.)

4 Click on File [image] Merge... to get the Merge File list box. Select BarChart.vee and place it to the right of the Formula object. Connect the two objects.

5 Run the program. It should look a follows.

Notice that the Bar Chart Display takes a one-dimensional array and displays the values as vertical bars. It uses the number of bars necessary to display the values in the array. To see how the program is created, open the detail view of the display. You can look at examples in the library directory for more ideas about programs.

note

The File [image] Merge command is used to merge in UserObjects and objects. The File [image] Merge Library command is used to merge UserFunctions.


Lab 10-1: Configuring a Test

note

The example explains how to implement the random() function with a certain range of test results expected, but you can use the same principles to configure other tests.

1 Select Device [image] Sequencer and place it in the upper-left work area.

2 Select Display [image] AlphaNumeric display, place it below the Sequencer, increase its width, and connect the Sequencer Log output terminal to the Alphanumeric data input.

3 Double-click the Sequencer transaction bar to get the Sequence Transaction dialog box. Set the fields as follows.

note

As you edit the fields, remember to click on new fields to modify them or use the Tab key to move forward to different fields. Use the Shift-Tab keys to move the cursor backward. Press the Enter key only when you are done editing the dialog box.

Field Name

Description

TEST:

The default name is test1, which you can use. This is just the label for the test in the Sequencer. It is not the test function itself.

SPEC NOMINAL:

Represents the expected test value. The default is .5. Change this to .25, and then alter the upper RANGE field (on the far right) from 1 to .5.

FUNCTION:

The default entry testFunc(a) holds the actual function that performs the test. In this case, replace the default field with the random()function. Random() will return a Real64 value between 0 and 1 simulating a test result. This result will be compared to the test specification.

The random(low,high) object is located in the Probability & Statistics category in the Function & Object Browser box. Remember that you can call this math function from any expression field without actually using a Formula object. If you do not provide the parameters low and high, as shown in this example, the function will use the default parameters 0 and 1.

You may leave the other defaults. This configuration will lead to a PASS result in approximately half of the runs. The dialog box should look like as follows.

Click OK to close the dialog box. You will see the transaction
test1 0 <= (.25) <= .5
on the first transaction bar. This means that test1 will pass if the returned value is in the range from 0 to .5 with the end points included. The expected result is about .25.

4 Run the program. It should display the name of the test, the test result, and the pass-fail indicator (1 for PASS, 0 for FAIL) in the display.

Before proceeding, study the following table to understand the various choices in the Sequence Transaction dialog box. Open the dialog box again by double-clicking on the transaction bar. Open the various menus and read about the different options.

Sequence Transaction Field

Description

TEST:

Unique name used to reference the test in the Sequencer. The default names start with test1 and increment with each test. Choosing TEST: means that a test result will be compared to specifications and branching will occur to the next test based on the configuration.

The TEST: button toggles to EXEC:. If you toggle TEST: to EXEC:, the test will execute without a comparison between a test result and specifications. For example, you might choose EXEC: when the UserFunction is setting up global variables. Selecting EXEC: will also disable logging for the test.

ENABLED

Determines when to execute a test. This menu displays four menu choices:

• ENABLED executes the test under all conditions.

• ENABLED IF: executes the test if the stated expression evaluates to TRUE. For example, the test might be enabled if the input pin A holds the value 1 (A == 1). You can use ENABLED IF: for audit test control. You might want a particular test to execute every ten runs, for instance.

• DISABLED is the opposite of ENABLED.

• DISABLED IF: is the opposite of ENABLED IF:.

SPEC

NOMINAL:

Expected value from the test.

RANGE:

Specifies the range of test values. This menu displays four menu choices:

• RANGE signifies the range of test values that signify a PASS condition. You may also choose from the usual comparisons: >, >=, <, <=, ==, !=.

• LIMIT uses just one value for a comparison of test data.

• TOLERANCE states the passing range of values by adding or subtracting the specified tolerance to the SPEC NOMINAL value.

• %TOLERANCE states the passing range of values by adding and subtracting a percent tolerance of the SPEC NOMINAL value to the nominal specification.

FUNCTION:

Specifies the test to run. You can call UserFunctions, Compiled Functions, Remote Functions, or you can write in an expression to be evaluated. The result of the function you call (or expression you evaluate) is tested against the specifications.

If a UserFunction returns more than one value, VEE assumes the top output pin holds the result to be tested.

Functions can also be combined and nested: (random(0,myfunc()+3,100)*2), for example.

LOGGING ENABLED

Logs test data. To specify logging options, open the Sequencer object menu, choose Properties, click on the Logging folder, and choose from the list. By default, Name, Result, and Pass are checked. There is also a field to choose between Log to Output Pin Only and Log Each Transaction To:. If logging is enabled, each test logs a record.

This button toggles to LOGGING DISABLED.

IF PASS

Determines branching instructions. If the test passes, VEE goes to this line for branching instructions. IF PASS tells VEE to branch according to the selection in the drop-down menu.

This button also toggles to IF PASS CALL:.

IF PASS CALL: tells VEE to call the stated function, then go to the branching menu selection.

(Refer also to THEN CONTINUE, which is the next item in this table.)

THEN CONTINUE

Determines test branching.The drop-down menu THEN CONTINUE (for IF PASS and IF FAIL) contains six branching options:

• THEN CONTINUE executes the next test configured in the Sequencer.

• THEN RETURN: tells VEE to stop executing tests and put the specified expression on the Return output pin of the Sequencer.

• THEN GOTO: jumps to the test named in its field.

• THEN REPEAT repeats the current test up to the number of times specified in the MAX TIMES: field. If the PASS/FAIL condition still exists after the maximum number of repeats, then VEE continues with the next test.

• THEN ERROR: stops execution by generating an error condition with the given error number. An error can be trapped with the Error output pin on the Sequencer. No other output pins will send data.

• THEN EVALUATE: calls the specified UserFunction, which must return a string that states a branching menu option. Valid string results from the UserFunction are: "Continue", "Return <expr>", "Goto <name>", "Repeat <expr>", "Error <expr>", where <expr> is any valid VEE expression and <name> is the name of a test in the sequence. This option allows you to ask the user what to do next.

IF FAIL

Branching instructions. If the test fails, VEE goes to this line for branching instructions. IF FAIL toggles to IF FAIL CALL:. Options are the same as for IF PASS.

DESCRIPTION:

Text comments on the test. They will show on the Sequencer transaction bar and can be stored with the test record by using the Logging folder in the Properties dialog box.

See Also

Adding or Inserting or Deleting a Test, Accessing Logged Test Data


Adding or Inserting or Deleting a Test

In this section, you add another test transaction to the Sequencer object. You can use the same random() function to simulate a test result, but this time you will compare the result to a limit instead of a range of values.

1 Double-click below the first Sequencer transaction bar to get the Sequence Transaction dialog box. Fill in the fields as follows:

Item | Description
test2 | Use the default.
SPEC NOMINAL | Change the settings from .5 to .25.
RANGE | In the drop-down menu, select LIMIT:. Choose < for the operator. Change 1 to .5 for the limit.
FUNCTION | Change the field from testFunc(a) to random().

Leave the other default selections and click OK to return to the Sequencer.

note

You could also add a transaction after the highlighted one by selecting Add Trans... from the object menu.

The Sequencer test plan should now have a second transaction that reads: test2 (.25) < .5. Now insert a transaction between these two tests.

2 Make sure the second transaction bar is highlighted. Then open the object menu and select Insert Trans.... Fill in the fields as follows:

Field | Description
TEST | Change the name field to Insert.
FUNCTION | Change to random().

Click OK. You will now see Insert 0 <= (.5) <= 1 on the second transaction bar. Run the program to see the three records from the three tests. (You may have to enlarge the display to see all the entries.)

3 Now delete Insert by clicking the Insert transaction bar, placing the mouse pointer over the Insert transaction bar, and pressing Ctrl-K.

note

You could also click the target transaction bar and select Cut Trans from the object menu. You can also paste a transaction that has been cut by choosing Paste Trans from the object menu (Ctrl-Y is the shortcut). And in a similar fashion, you can copy a transaction with the Copy Trans selection.

4 Run the program and note the two records of data from the two tests. Save the program as seq1.vee. The program should look like follows.

The braces indicate a Record data type. The Sequencer outputs a Record of Records, as shown in the AlphaNumeric display. This means you could put the sequencer in a loop and run the same sequence of tests several times yielding an array of Records of Records.


Accessing Logged Test Data

The Sequencer outputs a Record of Records. Each test uses the test name as its field name in the Sequencer record. The fields within each test are named according to the logging configuration. Using the default configuration with the fields Name, Result, and Pass, you could access the result in test1 with the notation Log.Test1.Result, as shown below.

.

The following steps access test results.

1 Open seq1.vee.

2 Select Device [image] Formula and place it below the display. Change the expression to Log.Test1.Result. (Remember that VEE is not case sensitive and the capitals in the names are for clarity in documentation.)

Change the input terminal name from A to Log. (You could leave the default name A. The formula would then read A.Test1.Result.) Connect the Sequencer output terminal Log to the Formula input terminal Log.

3 Select Display [image] AlphaNumeric display and connect it to the Formula output.

4 Run the program and it should access the Result field in Test1. Save the program as seq2.vee. The program should look like follows.

note

Each test creates a record, named with the test name, as it executes within the Sequencer. This record can be used in subsequent tests. For example, you could enable test2 if test1 passed (ENABLED IF: test1.pass == 1). If you need to access test data in an expression field while the test is still running, test data is stored in the temporary record thistest.

5 Change the formula to read Log.test1 and run the program again. It should retrieve the entire record for test1, which is indicated by the braces around the three values in the display.

6 By changing the formula, you can access the result, pass, name, and other fields in the test1 and test2 records. Select Logging tab in the Properties box and add the Nominal and Time Stamp fields to the logged records. Access these new fields with the Formula object.


Lab 10-2: Passing Data Using an Input Terminal

First, follow the steps to create the UserFunction Rand, which will simulate a measurement procedure. Rand() will add an input parameter to the output of the random(low,high) object, and put this result on the output pin. Rand() will be called from three different tests.

1 Select Device [image] UserFunction. Change the name from UserFunction1 to Rand.

2 Get the random(low,high) function, delete the input terminals, delete the parameters, and place it in Rand. (Recall that without parameters, the defaults will be 0 and 1.) Place an A+B object to the right of random(low,high). Connect the output of random(low,high) to the upper left input of the A+B object.

3 Add a data input terminal to Rand. Connect the input terminal A to the lower left input terminal of the A+B object.

4 Add a data output terminal to Rand. Connect the output of the A+B object to the Rand output terminal.

The UserFunction Rand should look like follows.

5 Save the program as seqdat1.vee. Close the Rand window using the x button on its top right corner.

note

Closing the window does not remove the UserFunction. If you want to check this, just click on Edit [image] Edit UserFunction and you will see Rand come up in a list box of UserFunctions to edit. Or you can iconize the Rand function and you will see the icon for it in the bottom of the VEE screen.

Now set up three tests in the Sequencer to call Rand using a Sequencer input pin to feed the input parameter to Rand.

6 Select Device [image] Sequencer and place it in Main. Add an input terminal to the Sequencer. Click the transaction bar to get the Sequence Transaction dialog box. Change the FUNCTION field from testFunc(a) to rand(a). This will call the UserFunction Rand() and send it the value on the Sequencer input terminal A. Click OK to get back to the Sequencer open view.

note

You could also use a Sequencer input terminal name, such as A, to pass data to any of the expression fields within the Sequence Transaction box. For example, you could use A to pass data to RANGE: and SPEC NOMINAL:.

Make sure the transaction is highlighted, place the cursor on the transaction bar, press Ctrl-K to cut the test, then press Ctrl-Y three times to paste the test back into the Sequencer. (You could also cut and paste using the object menus.)

The default test names will be test1x2, test1x1, and test1. Open the three Sequence Transaction dialog boxes and change these names to test1, test2, and test3 for clarity.

1 Select Data [image] Continuous [image] Real64 Slider and place it to the left of the Sequencer. Change the name to the prompt Select Num:, size the object to be smaller, and connect it to the Sequencer input terminal.

You can size an object as you place it by clicking and dragging the object corners using the left mouse button.

2 Select an AlphaNumeric display, place it below the Sequencer, enlarge it to be wider, and connect it to the Log output terminal on the Sequencer.

3 Save the program again as seqdat1. Select a number on the Real64 Slider object and run seqdat1. It should look like follows.

As the number of tests increases, passing data using an input terminal requires more and more input pins. To reduce the input pins, you could pass records to input terminals and use individual fields in the records for the separate tests. You could also use a separate UserFunction to set up global variables, which can then be called by other UserFunctions or any expression field within the program. The next exercise illustrates this.

See Also

Passing Data Using a Global Variable, Comparing a Waveform Output with a Mask


Passing Data Using a Global Variable

This exercise modifies the seqdat1 program by adding a global variable to pass the parameter a to the UserFunction Rand.

1 Delete the Real64 Slider object labeled Select Num. Delete the A input terminal on the Sequencer.

2 Highlight the test1 transaction bar, open the object menu, and click Insert Trans.... When the Sequence Transaction box appears, click TEST to toggle the selection to EXEC and change the name to Setup.

3 You will use EXEC mode, since the UserFunction will only set up a global variable and will not yield a result that needs to be tested against a specification.

4 Change the FUNCTION field to global() and click OK to close the dialog box.

5 You will now create the UserFunction global().

6 Select Device [image] UserFunction. Change the name UserFunction1 to global.

Select Data [image] Continuous [image] Real64 Slider and put it in the UserFunction, change the name to Select Num:, and size it to be smaller vertically.

Select Data [image] Variable [image] Set Variable and place it to the right of the Real64 Slider.

Change the global variable name from globalA to a. Connect the Real64 Slider to the Set Variable object.

To display the function on the screen for an operator to select a number, add a pop-up panel view. Include a Confirm (OK) button, so that the panel remains on the screen until the operator has made a selection. (It is also possible to do these tasks with a Real Input Dialog Box inside the global() UserFunction.)

7 Select Flow [image] Confirm(OK) and place it above the Real64 Slider object. Connect the OK data output pin to the Real64 Slider sequence input pin.

note

If you place the OK button below the Set Variable object it causes a logic error. That is because VEE sends the old value on the Slider to the Set Variable object and pauses until the OK button is pressed. Any new value you entered on the pop-up panel is ignored. When OK is connected above the Real64 Slider, VEE waits to set the global variable until after the OK is pressed, and therefore uses the new Slider value. You can turn on Show Data Flow to watch the execution order.

8 Select Display [image] Note Pad and remove the template information. Place it to the right of the OK button. Enter the following user prompt in the Note Pad:

Please select a number for this run of tests 1, 2, and 3.

9 Select the Note Pad, the Real64 Slider, and the OK button by pressing Ctrl and clicking on those objects. Each object will now have a shadow to indicate it is selected. Click Edit [image] Add To Panel. (Remember the Edit menu is also available via the right button on an open area of the VEE screen or the detail view of a UserObject or UserFunction.) In Panel view, size the panel to be smaller, and position the Note Pad on top, the Real64 Slider in the middle, and the OK button on the bottom.

note

When you reposition the objects in Panel view, it does not affect the layout of the objects in the Detail view

Open the UserFunction Properties window. In the General folder under Pop-up Panel, set the ShowPanelonExecute property to True. T UserFunction in detail view

The panel view:

10 Save the program as seqdat2 and run it. When the pop-up panel appears, select a value and press OK. It should look like follows.

note

The pop-up panel will appear in the center of the screen by default. To move it, click and drag the title bar.


Comparing a Waveform Output with a Mask

In this exercise, you will create a UserFunction called noisyWv and call it from a single transaction bar in the Sequencer. The operator will be able to vary the amplitude of the wave from 0 to 1. This function simulates a test result that returns a noisy waveform. You will use the Coord object in the Data [image] Constant menu to create a straight line mask at 0.6, which the Sequencer will use to test the noisy waveform.

1 Create the UserFunction called noisyWv in the Detail view.

2 Press Ctrl and click on the OK button, the Real64 Slider, and the Note Pad to highlight them for creating a Panel view. Select Edit [image] Add To Panel.

When the Panel view displays, rearrange the objects to your taste, and size the window.

Open the object menu, click Properties, and under Pop-up Panel click next to Show Panel on Execute.

The Panel view should look like this:

3 Select Device [image] Sequencer and place it left-center of Main. Add a data input terminal and name it mask.

4 Click the transaction bar to get the Sequence Transaction dialog box. Change fields as follows:

Field | Description
FUNCTION | Type in noisyWv().
RANGE | Click and select LIMIT from the pop-up menu. Leave the <=, and the LIMIT terminal name field type mask. All of the other defaults are fine, so click OK.

test1 will get a result from noisyWv() and test it against the limit value at the input terminal named mask. If the noisy wave is less than or equal to the mask at all points, it will pass. Otherwise, it will fail.

5 Select Data [image] Constant [image] Coord and place it above the Sequencer. Connect its output to the Sequencer input terminal mask.

Open the Coord object menu, click Properties, and set fields as follows:

Property | Description
DataShape | Set to 1D Array.
ArraySize | Type in 2 (you only need two pairs of coordinates to specify a straight line.)

6 In the Coord object, you now see two indices for pairs of coordinates. Double-click the first index, 0000: and a cursor will appear. Type in the coordinates separated by a comma, and VEE adds the parentheses automatically. Type 0, 0.6 Tab 20m, 0.6 and then click on the work area outside the object. The entries are as follows:

• The x axis (time axis) for the Noise Generator in noisyWv() goes from 0 to 20 milliseconds; hence, the two x values of 0 and 20m.

• The two y values are both 0.6, since you want a straight line mask.

note

You can create any mask waveform by configuring the proper number of coordinate pairs and filling them in.

The Sequencer comparison mechanism operates just like the Comparator object, which accepts the Coord data type to test waveforms. Of course, you could also compare two Waveform data types. Press Tab to move between coordinate pairs, and click on the work area when you are done.

7 Select an AlphaNumeric display, increase its width, and connect it to the Log output from the Sequencer.

8 Save the program as seqdat3 and run it. It should look as follows.

This completes the exercises about passing data with the Sequencer. In the next exercise, you will learn how to access and analyze data from several iterations of the Sequencer.


Analyzing Data from the Sequencer

Sequencer data comes out as a record of records. In many cases, however, the Sequencer may run through a series of tests several times. This generates an array of records. Each record represents one run through the Sequencer and holds other records, representing each test within a run. The easiest way to visualize this is to imagine a cube of data in memory, as follows:

The array of records is called Log, because that is the name associated with the Sequencer output pin. To access a particular run, use array indexing with the bracket notation.

• Log[0] is the first run through the Sequencer, Log[1] is the second run, and so forth.

• The main record for each run has two fields, Test1 and Test2.

• Within the record Test1 there are three fields: Name, Result, and Pass. The same holds for the record Test2.

• Therefore, Log.Test1.Result gives an array of four values, each representing one of the four runs. Log[0].Test1.Result outputs a scalar value, the Result of Test1 in the first run (Log[0]).

The logged array of records simplifies analyzing and investigating the data. For example, you might want to know how many tests passed in a particular run. Or you might want to average the results of Test2 in all runs. Or you might want to see all of the data on Test1 in the fourth run. All of these queries are possible with this data structure.

See Also:

Lab 10-3: Analyzing Several Runs of Data from the Sequencer


Lab 10-3: Analyzing Several Runs of Data from the Sequencer

1 Clear the screen and open the seqdat1.vee program.

Modify the seqdat1.vee program to run through the Sequencer three times. Then perform some analysis operations on the data.

2 Select Flow [image] Repeat [image] For Count and place it above the Real64 Slider object. Change the number of iterations to 3, and connect the data output pin to the sequence input pin of the Sequencer.

3 Delete the data line between the Sequencer Log pin and the display. Select Data [image] Collector and place it to the right of the Sequencer. Connect its upper left data input pin to the Sequencer Log pin and its XEQ pin (lower left) to the sequence output pin on the For Count object. Connect the Collector data output pin to the AlphaNumeric display. Enlarge the display vertically somewhat to accommodate an array with three elements.

The Sequencer will now run through test1 and test2 three times and collect the data into an array with three elements, each one holding a record of records for each run. (Refer to the cube of data to visualize this.)

Run the program at this point to see the display of the Sequencer data.

Now use the Formula object to extract part of the data to analyze. This exercise uses the results of test1 for all three runs as an example, and finds the mean of that array.

4 Select Device [image] Formula and place it below the display. Connect the Formula input pin to the output of the Collector. Change the Formula input field to read: a[*].test1.result. Connect a mean(x) object to Formula, and an AlphaNumeric display to mean(x).

The a refers to the array on the input terminal A. Test1.result accesses the proper field. All runs will be shown in an array. (A[0].test1.result would refer to the first run only, for example.)

5 Run the program. It should look like below.

Although this exercise accesses a single array, the principle is the same for extracting other arrays of data from the Sequencer output. Note that you can easily change which fields are saved for each by opening the Logging folder in the Sequencer Properties dialog box.

See Also

Analyzing Data from the Sequencer


Lab 10-4: Using the To/From File Objects with Logged Data

1 Open the seqdat2 file and delete the data line to the display.

2 Select Flow [image] Repeat [image] For Count and place it to the left of the Sequencer. Change the For Count number to 3, and connect its data output pin to the sequence input pin on the Sequencer.

3 Enlarge the work area vertically and place the AlphaNumeric display near the bottom. Select Data [image] Collector and place it in the left work area. Connect the Sequencer Log pin to the Collector data input pin. Connect the For Count sequence output pin to the Collector XEQ pin.

The Collector will create an array of records of records from the Sequencer. Using the WRITE CONTAINER transaction in the To File object you can write any VEE data container to a file quite easily.

4 Select I/O [image] To [image] File and place it to the right of the Collector. Select I/O [image] From [image] File and place it below the To File object. Add an input terminal to the To File object and connect the Collector output to it. Connect the To File sequence output to the From File sequence input pin. Connect the From File data output to the display.

Check Clear File At PreRun & Open in To File, and configure a WRITE CONTAINER a transaction. Configure a transaction in the From File object like the following: READ CONTAINER x.

You can use the default data file for storage.

5 Save the program as seqdat4.vee and run it. It should look as follows:

See Also

Using the To/From DataSet Objects with Logged Data


Using the To/From DataSet Objects with Logged Data

Since you are storing test data as records, you may prefer to use the To/From DataSet objects. In this case you do not need a Collector, because you can append each run of the Sequencer to the end of the DataSet.

Modify the program seqdat4.vee to look as follows. The To/From DataSet objects are in the I/O menu. Notice the sequence line going into From DataSet. The sequence line is included because you want to wait for all three runs to be appended to the DataSet before you trigger From DataSet

.

One reason you might use the To/From DataSet objects to collect data instead of the To/From File objects is because you can convert the data to useful information with the Search Specifier feature in the From DataSet object.

note

Remember to change the Get records field in From DataSet from One to All.


Lab 11-1: Using Menus

In this exercise, you will create an operator interface that includes a menu with three choices: die1, die2, and die3. When the operator selects a choice, a function by the same name will be called that displays a die with one, two, or three dots on its top face. This program simulates a situation where the operator must choose a test to run from a menu. You will also learn how to import a bitmap to change the appearance of an icon. This will be called the Dice Program.

Begin by creating the three UserFunctions.

1 Select Device [image] UserFunction.

Although you could use any icon to display the imported bitmap, this example uses the Picture object.

2 Select Display [image] Picture and place it in the UserFunction.

3 Open the Picture object menu, click Properties, then set ShowTitleBar property to False. Select die1.gif under Picture, click Scaled, then OK.

note

To access an object menu when Show Title Bar is turned off, click the right button over the object.

note

Although VEE defaults to the bitmaps subdirectory, you could use a bitmap from any directory.

You should now have a picture of a die with one dot on its top.

4 Select Flow [image] Confirm (OK) and place it below the die. Connect the Picture sequence output pin to the OK sequence input pin.

5 Select the Picture and the OK objects (press Ctrl and click the objects to create a shadow). Open the pop-up Edit menu by placing the mouse pointer on the background and pressing the right mouse button. Select Add to Panel.

6 Change the UserFunction Title and Panel Title to die1. Arrange the objects and size them as desired.

note

To move objects in Panel View, right-click on the object and select Move or highlight the object (the object should show a gray border) and drag it to its new location.

Select ShowPanelonExecute from the Properties dialog box. Click the Panel folder and activate the PanelGridSize property and change the grid size to 2 for more accurate alignment. Then click OK.

7 Create two more UserFunctions by selecting Clone in the die1 object menu. The new UserFunctions appear automatically as die2 and die3. Change the picture objects to die2.gif and die3.gif respectively. Check all the settings of the new functions to make sure they match die1 except for the names and bitmaps. The program should look as follows. Iconize the function windows.

Create a menu to select one of these three functions to call.

8 Select Data [image] Selection Control [image] Radio Buttons.

Radio Buttons is an object that outputs an enumerated value (the Enum data type: a text string with an ordinal number associated to it) from a user-defined list on its upper output pin. For example, if you define the list as Monday, Tuesday, Wednesday, Thursday, and Friday, the operator could select the day from a menu, and Radio Buttons would then output the day.

The first item in the list is assigned the ordinal position 0; the nth item in the list is assigned ordinal position n-1. For instance, Monday in the list above has an ordinal position of 0, and Friday has an ordinal position of 4. The ordinal position appears on the lower output pin. Read the Help entry in the object menu for a more detailed explanation.

9 Open the Radio Buttons object menu and select Edit Enum Values....

Type in the names of the functions die1, die2, and die3 by pressing the Tab key between each entry except the last. Click OK.

note

There are six menu formats for data selection control. Radio Buttons displays entries as buttons. The operator's selection is output in text format as an Enum data type. Cyclic Button cycles through the enumerated values one at a time as the operator clicks the button. List displays all of the enumerated values in a list with the selected item highlighted. Drop-down list, Pop-up list, and Slider list are the other three choices.

10 Open the Radio Buttons object menu, click Properties, then select Auto Execute. Change the title to the prompt: Make a Selection:

Set up a Call object so that the value the operator selects on the Radio Buttons object will now become the function name that the Call Function object calls.

11 Click Device [image] Call. Select Add Terminal [image] Control Input, then select Function Name, and click OK. The Function Name control pin accepts an Enum or Text value as input. Connect the Radio Buttons data output pin to the Function Name input terminal on the Call Function object. Connect the Radio Buttons sequence out pin to the sequence in pin of Call Function. Click on die2 in Make a Selection: and notice that the Call Function Name changes to die2.

note

The Call input terminal requires a Text Scalar, so VEE converts the Enum Scalar to a Text Scalar.

Remember the dotted line indicates a control pin. When Auto Execute is turned on, Radio Buttons executes whenever you make a change to it and sends the selection to Call. The control pin on Call Function replaces the function name as soon as the pin receives data. The Call object does not call the specified function until its sequence input pin is fired.

note

When a program uses Auto Execute and the sequence pins, the operator does not have to click the Run button to begin the program.

Add an operator interface showing only the prompt, the menu, and the pop-up panels showing the selections.

12 Select the Radio Buttons object by pressing Ctrl and clicking on the target object. Then select Edit [image] Add To Panel.

13 Open the object menu, select Properties, and adjust the colors and fonts if desired.

Run the program by making a selection. (Do not use the Run button, because it will use the selection that is already made on the menu.)

The program should look like following figure when executing.

There are a few things to note before the next lab exercise:

• You can use the same techniques in the exercise above to create menus for any program.

• Radio Buttons could also be used to select a compiled language program by using the Execute Program object with a control pin (“Command”) that indicated the program to call. If you had imported a library of compiled functions, you could also use the Call object to run a function from the library.

• You could optimize this program by using the File Name data input pin on the Picture object inside a single UserFunction, and then sending the appropriate bitmap file to the object. If you are using many different bitmaps, this is a more efficient way to program.

• You will usually use Run instead of AutoExecute on more complicated programs. You can have the program pause at a data constant or selection control object by using Wait for Input instead of AutoExecute.


Lab 11-2: Importing Bitmaps for Panel Backgrounds

Bitmaps are not essential to your programs, but they can add clarity and impact to tests. For example, you might want to import a schematic to better illustrate what is being tested. In this exercise, you will import bitmaps for panel backgrounds with standard VEE objects placed on top of them.

Bitmaps can be imported for icons, the Picture object, or for the panel view backgrounds in UserObjects or UserFunctions. You will create a pop-up UserFunction called Bitmap that includes a Label object and a Confirm (OK) object.

1 Select Device [image] UserFunction.

2 Select Flow [image] Confirm (OK) and Display [image] Label, and place them in the UserFunction window.

3 Change the name of the UserFunction to Bitmap.

4 Select the OK and the Label objects to highlight them with a shadow. Open the pop-up Edit menu by placing the pointer on the UserFunction work area and clicking on the right mouse button. Select Add to Panel.

5 Open the UserFunction menu, select Properties, then select ShowPanelonExecute. (Remember to double-click on the title bar to get the Properties box.) Deselect Show Title Bar under Pop-up Panel.

Open the Panel folder, change the Grid Size to 2, select default.gif and Scaled under Background Picture, then click OK.

6 Open the Properties box for the Label object, and set as follows:

Label Properties | Description
Title: | Change to Bitmap Function.
Justification | Change to Center.-
BackColor | Select Light Gray and click OK.
Font | Choose a larger font with bold type, and click OK. Check Automatically Resize Object on Font Change.
Border | Click on Raised. Click OK to make the changes and close the Properties dialog.

7 Position the title Bitmap Function and the OK button as desired. Iconize the Bitmap UserFunction.

8 Go to the Main window. Click Device [image] Call, then click Select Function in the object menu, and choose Bitmap. Run the program. The pop-up box should look as follows.


Lab 11-3: Creating a High Impact Warning

This exercise includes several UserFunctions that are nested. The first UserFunction is the alarm itself, which displays a red square and beeps. The second UserFunction calls the alarm repeatedly creating a blinking light effect and a pulsing sound, until the operator turns the alarm off.

Begin by programming the alarm function.

1 Select Device [image] UserFunction. Change the name to alarm.

2 Select Display [image] Beep and place it in the upper-left of the UserFunction. Adjust the settings so there is a loud beep that lasts a second. Change the Duration (sec) field to 1. Change the Volume (0-100) field to 100.

note

These instructions assume your computer has the hardware to support a beep. Some Windows Vista, Windows 2000 and Windows XP systems have modified the Default System configuration for the Default System Beep.

note

You do not need to connect the Beep object to anything. It activates when the function executes.

3 Click Display [image] Indicator [image] Color Alarm and place it in the UserFunction. Open the Color Alarm object menu, click Properties, and set as follows: set the ShowTitleBar property to False. Set the Shape property to Rectangular. Set the HighLimit property to .66, and delete any text beside HighText property.

4 Click Data [image] Constant [image] Real64, change it to 1, and connect it to the Color Alarm input pin.

5 To keep the display on screen for one second to synchronize with the Beep object, use a Delay object set to 1 second.

6 Select Flow [image] Delay, set it to 1, and connect its sequence input pin to the Color Alarm sequence out pin. The alarm will then last one second.

7 Select Display [image] Note Pad and remove the template. Add the message: TURN OFF INSTRUMENTS!. Size the Note Pad as needed.

8 Go to the Main window. Choose Device [image] Call, choose Select Function from the Call object menu, and select alarm. Run the program to test it. The detail view of the UserFunction alarm should look like follows.

9 Return to the alarm window. Select the Color Alarm display and the Note Pad. Open the pop-up Edit menu and select Add To Panel. In panel view, size and arrange the objects using the object handles, the Align function, or by moving the objects. Set the PanelDrawGrid property to True if you need snap-to-grid. Open the Note Pad object menu and click Properties. Set as follows:

Property | Description
ShowTitleBar | False
EditEnabled | False
Border | Change to a Raised border.

10 Change the Color Alarm to a Raised Border as well.

11 Click on open space within UserFunction to get the Properties dialog box, and select ShowPanelonExecute. Set the property ShowTitleBar to False. Change the Panel Title to alarm. Iconize alarm.

12 Go to the Main window and delete the Call object. (VEE will still hold the function alarm in memory. If you want to edit the function again, select Edit [image] Edit UserFunction or double-click on its icon.)

13 Create the function that repeatedly calls the alarm function.

14 Select Device [image] UserFunction and change the name of the UserFunction to warning.

15 Select Flow [image] Repeat [image] Until Break.

16 Select Device [image] Call, change the Function Name to alarm, and connect its sequence input pin to the Until Break data output pin.

Add a Check Box object to ask the operator if he or she wants to turn off the alarm.

17 Select Data [image] Toggle Control [image] Check Box. Open the Check Box Properties box, change the Title property to Turn off alarm?, select the Scaled property and set it to True, select InitializeAtPreRun and make sure the property value is False, make the TitleFont property size bigger for the name. Connect the Call sequence out pin to the Check Box sequence in pin.

This creates an input object that uses a Check Box. If the operator clicks the box, an X will appear and the object outputs a 1; otherwise, the object outputs a 0. The output can be tested with an If/Then/Else object to tell VEE what to do next.

18 Select Flow [image] If/Then/Else and place it to the right of the Toggle. Connect the Toggle data output to the data input A of the If/Then/Else object. Edit the expression in the If/Then/Else object to: a == 1. (Recall that the symbol for is equal to is ==, not =.) If the terminal A holds a 1, the Then output will fire; otherwise, the Else output fires.

Connect the output of Toggle to the input of If/Then/Else.

19 Select Flow [image] Repeat [image] Break and connect it to the Then output on the If/Then/Else object as follows.

20 Select the Check Box object (Turn off alarm?)by clicking on the right side of the object. Open the pop-up Edit menu and select Add To Panel. Size the panel view to surround the Check Box.

21 Open the warning UserFunction Properties box, select ShowPanelonExecute, set the ShowPopupPanelTitle to False (since the title serves no purpose to the operator).

22 Go to Main and click Device [image] Call, open its object menu, click Select Function, then select warning. Move the Call object to the top center of the screen. Iconize the Main window.

23 By default, VEE displays both the alarm and the warning panels in the center of the screen, so the alarm will blink on top of the check box that will stop the alarm. Since both of these screen positions are not locked, you can reposition them on the screen by clicking and dragging the pop-up panels to new locations. However, with the alarm panel blinking this is somewhat difficult. Instead, click and drag the edge of the panel. If needed, stop the program using the stop button on the tool bar. Run the program.

When you have the two panels positioned as follows, you can stop the program by clicking the box next to the Turn off alarm? prompt.


Lab 11-4: Using an ActiveX Control

This lab shows how to use an ActiveX Control within VEE. You can incorporate ActiveX Controls from other applications into VEE programs. In this case, you will incorporate a ProgressBar control and use a loop to show the progress bar 0% to 100% complete. The same general principles apply to other ActiveX Controls.

1 Click Device [image] ActiveX Control References... and select Microsoft Windows Common Controls 6.0. Click OK.

2 Click Device [image] ActiveX Controls [image] ProgressBar. Size the ProgressBar object to be larger. Open its Object Menu and notice that the object name is ProgressBar. VEE has automatically created a declared variable that refers to the ActiveX control object. You can use the name ProgressBar in Formula expressions, just like any other variable or data input.

3 Click Device [image] Formula & Object Browser, and select ActiveX Objects, Library: MSComcltLib, Class: ProgressBar, Members: Value, and click Create Set Formula. Place the object at top center in the Main window.

4 To loop from zero to one hundred and show the percent complete, you will add a For Range object. Select Flow [image] Repeat [image] For Range, place the object below the ProgressBar, and set it as follows: From: 0, Thru: 100, and Step:10. Connect the For Range output to the ProgressBar input terminal Value.

5 To slow down program execution so that you can see the ProgressBar updating, select Flow [image] Delay and place the object to the right of the For Range object. Set it to .2. Connect the ProgressBar sequence output pin to the Delay object sequence input pin and run the program.

note

ActiveX Control object menus have both Properties and Control Properties. The Properties menu sets the VEE properties of the object. The Control Properties are supplied by the Control and can be different for each type of ActiveX Control.

Examine all the control examples that ship with VEE to get a better understanding of how they work. Then look for other controls and displays in the marketplace you might want to add to enhance the user interface capabilities in VEE.

Following figure shows another example of VEE incorporating a control from MS Chart. After you have selected a control library in the Device [image] ActiveX Controls References dialog box, you can use the Function & Object Browser or the Declare Variable Object to identify a control's properties and methods.


Lab 11-5: Creating a Status Panel

In this lab, you will learn how to use the functions from the dice program to create a status panel. (The dice program exercise is in Lab 11-1: Using Menus) Typically this would be used with the Sequencer object when there are a number of tests and you want to see the results as they are returned. You will use the function random(), which returns a real value between 0 and 1, when using the default settings.

1 Click Device [image] Sequencer. Double-click the transaction bar, and configure your test using the default name, test1, and replacing the FUNCTION: field with random(). See follows.

2 Configure a second test the same way named test2.

3 Open the Sequencer Properties box, choose the Logging tab, and under Logging Mode select Log Each Transaction To: logTest(thisTest), then click OK.

As the Sequencer executes each transaction, it creates a record for each test called "thisTest," whose fields can be configured under the same tab. You can then create a UserFunction called "logTest" (or another name) and the Sequencer will call the LogTest() UserFunction with the Record thisTest at the end of each transaction that is executed. In this way, you can update the status panel.

4 Select Device [image] Function & Object Browser [image] Built-in Functions [image] Panel [image] showPanel and place it above the Sequencer. Delete the input pins, then edit the parameters to "logTest",420,180 leaving out the last two parameters. Connect the Result output pin from showPanel to the Sequencer sequence input pin. ShowPanel outputs a 1 if it succeeded.

LogTest is the name of the UserFunction. The other two parameters are X and Y coordinates on your screen starting from the upper left corner. This tells VEE where to place the UserFunction panel when it is shown. (The panel dimensions are not included in this example.)

5 Create the UserFunction named logTest, as shown below. Add an input pin. (The logging Record will be the input.) Put the Logging AlphaNumeric on the panel and connect it to the input pin. Select Logging AlphaNumeric and click Edit [image] Add to Panel. In the panel view, adjust the sizing and placement as desired. Deselect the display and panel title bars.

The next figure shows the panel view after running the program. It will give you an idea of how the data will be displayed.

6 Select hidePanel from the Function & Object Browser box and Flow [image] Confirm(OK). Change the hidePanel() parameter to logTest. Delete the input pin. Connect the objects as follows.

7 Run the program. It should look like follows.

In summary, the showPanel object displays the UserFunction panel, but does not call the UserFunction. The Sequencer calls the UserFunction twice through its logging function, and each call updates the panel. Then, when the operator is done, he or she can press OK and the panel is hidden. This example uses an OK object to trigger the hidePanel object, but you could put it elsewhere in the program to time its execution. Step through the program to see the status panel appear, update with the results from Test1 and Test2, and then disappear.


Lab 13-1: Practice Session with Agilent VEE Web Browser

This exercise simulates a Web session where you provide the Solitaire.vee program for a remote user to view on your system. In this case, there is an error in the program and the remote user is consulting with you on how to resolve the error.

1 Start VEE. Select File [image] Default Preferences [image] Web Server dialog box and click on Enable Server. Use the default settings. Open the Solitaire.vee program that you want the remote user to view. Run your network browser.

2 Contact the remote user and let him or her know to enter http://Server5 to reach your system over the Web. (You would use your computer name instead of http://Server5.)

3 When the remote user enters the URL http://Server5 the remote user sees your VEE Web Server Home Page displayed in his or her browser. (To review what the display looks like, refer to Displaying the Agilent VEE Web Server Page).

4 The remote user decides to view the entire VEE program first. In the VEE Web Server Home Page, he or she clicks Main Detail [image] View. The browser displays the view.

Above figure displays the Main program in VEE.

note

For this exercise, the Solitaire.vee program includes an error that is not in the VEE program example. If you would like to view the program, it is located in Help [image] Open Example... Games [image] Solitaire.vee.

5 The remote user clicks Back in the browser to display the VEE Web Server Home Page and chooses Last Error Message. The browser displays the error message.

Notice that the VEE error message specifies the UserFunction makeAMove.

6 The remote user goes back to the VEE Web Server Home Page once again and clicks on Detail View of UserFunction, and types in the UserFunction name makeAMove. The browser displays the UserFunction makeAMove as follows.

The remote user is able to see the error in the VEE program. There is an input pin not connected on the JCT object shown in above figure. The remote user could now help you troubleshoot Solitaire.vee and resolve the error. Using a similar process of working together over the Web, you could collaborate with remote users or develop programs together.

See Also

The Callable VEE ActiveX Automation Server, Web Monitoring with Agilent VEE, Providing Agilent VEE Data to a Remote User, Web Server Dialog Box, How a Remote User Accesses Agilent VEE on Your System, Displaying the Agilent VEE Web Server Page, Restricting Access to Programs Viewed over the Web


General Programming Techniques

The following exercises give you a chance to practice the VEE concepts. The exercises are divided into categories.

To use this exercise, develop a solution and then compare it to the answers listed. There are many ways to program a given task, so you have a valid solution if it meets the problem specifications. However, programs that execute more quickly and are easier to use are probably better solutions. Each solution includes a short discussion of key points.

General Programming Techniques

Using Strings and Globals

Optimizing Techniques

UserObjects

Agilent VEE UserFunctions

Creating Operator Panels and Pop-ups

Working with Files

Records

Test Sequencing


Apple Bagger

You want to know how many apples it takes to fill a ten pound basket. Create a VEE program that counts how many apples it takes to fill the basket. Each apple weighs between 0 and 1 pound.

Suggestions

This program can be created with 10 or fewer objects. Choose from the following objects:

Start

Until Break

random() function

Accumulator

Break

Real64

Conditional (A>=B)

Stop

Counter

If/Then/Else

Alphanumeric

note

The VEE programs for many of the lab exercises and programming examples in this manual are included in VEE, under Help [image] Open Example... Manual [image] UsersGuide.

Solution 1—Apple Bagger

Key Points

Optimal Solutions:

To optimize the performance of programs, use fewer objects, if possible. This solution uses six objects. The program could also be implemented with 10 objects as follows.

Until Break and Break Objects:

Use these objects for loops that require testing a condition. In this example, the loop should stop when the total weight of the apples is greater than 10 pounds.

Accumulator:

Use the Accumulator to keep a running total.

Counter:

Use the Counter to keep a running count. In this example, the Counter is used to track the total number of apples in the basket. Note that when the total weight is over 10, only the Then pin fires on the If/Then/Else object giving the correct answer in the Counter.

Solution 2—Apple Bagger

This is another solution using more objects.

Key Points

Start:

Using a Start object for this program is redundant, since you can use the Run button on the main menu bar. Start is best used when you have two programs on a screen, and you want to be able to run them independently. Or you have a program with a feedback loop, and you want to define where to initiate execution.

Shift Register:

You use a Shift Register to access the previous values of the output. In solution 2, the Counter is keeping a running count of every apple before it is weighed, so the count must be reduced by one when the total weight exceeds 10.

Gate:

The Gate is used to hold the output until another action occurs and activates its sequence pin. Here, when the condition A<=10 is no longer true, the Else pin on the If/Then/Else object activates the gate.


Testing Numbers

Testing Numbers, Step 1

Create a program that allows a user to enter a number between 0 and 100. If the number is greater than or equal to 50, display the number. If it is less than 50, display a pop-up box with the message “Please enter a number between 50 and 100.”

Suggestions

This program can be created with 5 or fewer objects. Choose from the following objects:

Start

Int32

Slider

Real64

If/Then/Else

Formula

Gate

Text

Junction

Alphanumeric

Message Box

Solution—Testing Numbers, Step 1

Here is a solution to the Testing Numbers exercise using five objects.

Testing Numbers, Step 2

After the model is working with five objects (the Message Box produces the pop-up), try programming it with four objects without using the Gate object.

Solution—Testing Numbers, Step 2

The solution to the Testing Numbers exercise with four objects.

Key Points

Auto Execute:

All input objects such as the Int32 Slider have an Auto Execute selection in the Properties Box. If chosen, the object operates whenever its value is changed without needing to press Start or the Run button.

Consolidating Formulas:

The expression (A>=50)*A in the If/Then/Else object evaluates to a 1*A, if A>=50 is true, or 0, if false. So A is put on the Then pin, if the expression is true, and a 0 is put on the Else pin, if the expression is false. (Any expression that evaluates to a non-zero is considered true, and the value is propagated on the Then pin.)

Testing Numbers, Step 3

Create a solution using only three objects.

Hint: Use a triadic expression in the Formula object. The format is: (<expression> ? <if TRUE,output value> : <if FALSE, output value>). For example, if A < 10 evaluates to TRUE, you want the value of A on the Result pin; otherwise, you want the string “FALSE” on the Result pin. You would use the following triadic expression: (A<10 ? A : "FALSE").

Solution—Testing Numbers, Step 3

The solution to the Testing Numbers exercise using only three objects.

note

This could be implemented using a Real64 Input dialog box with its automatic error-checking capability. However, the operator must enter a valid number before the program can complete.


Collecting Random Numbers

Create a program that generates 100 random numbers and displays them. Record the total time required to generate and display the values.

Suggestions

This program can be created with six or fewer objects. Choose from the following objects:

Start

For Range

Until Break

randomseed() function

random() function

Collector

Formula

Set Values

Alloc Int32

Logging AlphaNumeric

Strip Chart

Meter

Date/Time

Timer

Now()

Break

Do

Hint: To improve performance, send the data to the display only once by first collecting the data into an array using the Collector object. Note the performance differences.

Solution—Collecting Random Numbers

Following figure is a solution for the exercise Collecting Random Numbers.

Key Points

Logging AlphaNumeric vs. AlphaNumeric:

Use Logging AlphaNumeric to display consecutive input (either Scalar or Array 1D) as a history of previous values. Use AlphaNumeric to display data from only one execution (the last) as a single value, an Array 1D, or an Array 2D. The Logging display is an array without index values; the AlphaNumeric display is the same array with optional index numbers and values.

Timing Pins:

The Do object controls which object executes first. The end of the program is timed from the sequence out pin of the For Count object, because that pin does not fire until all objects inside the loop have executed.


Random Number Generator

Random Number Generator, Step 1

Create a random number generator that requires external inputs. Display the numbers on a strip chart. Inputs should be allowed for:

Maximum random number

Minimum random number

Number of random numbers generated

Solution—Random Number Generator, Step 1

A solution for the first step of the Random Number Generator exercise.

Key Points

Layout of Slider Objects:

You can select either a vertical or horizontal format for the screen image of the slider objects by clicking on Horizontal under Layout in the Properties box.

XY Trace:

Use an XY Trace to display the recent history of data that is continuously generated.

Random Number Generator, Step 2

Collect the random numbers into an array. Find the moving average and display it with the numbers.

Solution—Random Number Generator, Step 2

A solution for Random Number Generator, step two:

MovingAvg(x, numPts):

Use this object located in the Function & Object Browser, Data Filtering category to smooth the input data using the average of a specified number of data points preceding the point of interest to calculate the smoothed data point.


Using Masks

Mask Test, Step 1

Create a 50 Hz sine wave with an adjustable amount of noise. Test the noisy sine wave to be certain that it stays below the following limits:

(0,0.5)

(2.2m, 1.2)

(7.2m, 1.2)

(10.2m, 0.5)

(20m, 0.5)

If the sine wave exceeds the limits, mark the failing points with a red diamond.

Hints: You can change the format of the displays from lines to dots to diamonds. (In Properties, choose the Traces tab for each trace input, the line type can be solid, dashed, points only, etc. Also the Point Type can be just a point, a diamond, box, or other shapes.) You may find the Comparator object helpful.

Solution—Using Masks, Step 1

A solution for step 1:

Using Masks, Step 2

Add to the program to calculate and display the percentage of failures.

Solution—Using Masks, Step 2

This is a solution for step 2.

Key Points

Mask:

The mask is created using the Data [image] Constant [image] Coord object, then configuring it for five array elements. You input the coordinate pairs separated by commas and VEE adds the parentheses. The x values were chosen knowing that the time span of the waveform was 20 milliseconds. Also, note that the Waveform (Time) display will accept a Coord data type as an input. You could also use a Data [image] Build Data [image] Arb Waveform object, which converts a Coord to a Waveform data type by specifying the number of points in the Waveform.

Comparator:

This object compares a test value against a reference value. Once again, you can compare a waveform to an array of coordinate pairs. The Failures pin gives you an array of the data points that failed, which you can send to the display and highlight with a different color or type of line.

TotSize:

This object simply gives you the number of elements in an array. Since this array contains the number of failures, dividing this by the total number of elements in the original waveform, 256, and multiplying by 100 gives us the percentage of failures.

Formula:

A/256*100 is the formula used to compute the percentage of failures, since the Function Generator and Noise Generator are set to put out 256 points.


Manipulating Strings and Globals

Using string objects or functions, create a program that accepts a user's name in the following format: <space> <firstname> <space> <lastname>. After the user enters a name, have the program strip off the first name and only print the last name. Store the string into a global variable. Retrieve the string using the Formula object.

Solution—Manipulating Strings and Globals

A solution to the exercise Manipulating Strings and Globals is shown below.

Key Points

String Objects and Functions:

StrTrim(str) first strips off any spaces or tabs from the front and back of the name. StrPosChar(str1, " ") yields the index of the space character between the firstname and lastname. StrLen(str), of course, gives the length of the string. All of these were performed using the string objects, but they could also be done using string functions within a Formula object.

Formula Object:

StrFromThru(A,B+1,C-1) takes the string from input A, adds 1 to the index of the space from input B, and subtracts 1 from the string length at input C. (Recall that all indexing is zero-based.)

Set Variable:

Notice how easily you can set a global variable called lastname, which can then be referenced in any expression field, such as the Formula object in this example.

Optimizing:

The three formulas could be combined into one formula. It is recommended to leave strTrim() on its own since its output is used multiple times, but the others could be combined into one to optimize speed. (This could reduce readability, however.)


Optimizing Techniques

For this lab, you will build a VEE program two different ways and note the difference in execution speed.

Optimizing Techniques, Step 1

Create a program that sends the range 0 to 710 step 10 through both a sine function and cosine function. Put the results of the functions on an X vs.Y display. Use the Timer object to clock how long the program takes. (Set your default preferences for Trig Mode to Radians.)

Solution—Optimizing Techniques, Step 1

Here is a solution to step 1.

Optimizing Techniques, Step 2

Clone all of the objects from the first program. Modify the new set to collect the range into an array. Now, the sine and cosine functions are run against an array of points, and only plotted one time. Note the time savings.

Solution—Optimizing Techniques, Step 2

This is a solution to step 2.

Key Points

Optimizing with Arrays:

Note the increase in performance between step 1 and step 2 that comes from using arrays. Whenever possible, perform analysis or display results using arrays rather than scalar values.

X vs. Y Display:

This example uses this display instead of the Waveform or XY displays, because there is separate data for the X and Y data.


Random Noise UserObject

Random Noise UserObject, Step 1

Create a UserObject that generates a random noise waveform. Display the noisy waveform and the noise spectrum outside the UserObject. Provide control outside the UserObject for the following: amplitude, number of points, interval (time span), DC offset.

note

Do not use a virtual source inside the UserObject. Use objects such as Build Waveform and Random to create the UserObject.

Solution—Random Noise UserObject

This is a solution for the Random Noise UserObject.

Solution—NoiseGen Object in Random Noise

One solution for the NoiseGen UserObject is as follows.

Key Points

UserObject:

Notice that the UserObjects you build are essentially customized objects that you add to VEE.

Build Waveform:

This object creates a Waveform data type from a Real array of amplitude values and a time span (the length of time in seconds over which the y data was sampled).


Using UserFunctions

UserFunctions, Step 1

Create a function called NoiseGen that accepts an amplitude value (0-1) from a slider and returns a noisy waveform.

Do Not Use

Virtual Source

For Count

For Range

Do Use

Formula

Ramp

Build Waveform

Hint: Use randomize(array, -a,a) where the array must be 256 points, and a is the amplitude. Build a simple main program that calls this function to be certain the function works correctly.

Solution—UserFunctions, Step 1

Here is a solution for step 1.

Key Points

Ramp():

Notice that the ramp() function is used to generate an array of 256 points within the parameter list for randomize().

Build Waveform:

Notice that the default time span is 20 milliseconds, so that you only need to send an array to this object to build a waveform.

UserFunctions, Step 2

In the same program, create another function called AddNoise that calls the first function NoiseGen. AddNoise should add the noisy waveform from the NoiseGen function to a sine wave. AddNoise should have two inputs, one for the NoiseGen amplitude and one for the sine wave. It should have one output for the result.

Build a simple main program with a slider for the noise amplitude, and the Virtual Source [image] Function Generator (sine wave, Freq = 100 Hz) for the good waveform to add to the noise. Display the resultant waveform.

Solution—UserFunctions, Step 2

This is a solution for step 2.

UserFunctions, Step 3

In the same program, call the AddNoise function again, this time from a Formula object, taking the absolute value of the result. Display the absolute value waveform on the same display. Next prepare to edit the AddNoise function. Turn on Debug [image] Show Data Flow. Leave the AddNoise window open and run the program. Notice how useful this capability is for debugging.

Solution—UserFunctions, Step 3

A solution for step 3:

UserFunctions, Step 4

Now change the program so that the slider sets a global variable called Amplitude. Have the NoiseGen function use that global (so NoiseGen will no longer require an input pin). Make the program run correctly. Save this file as uflab.vee.

Solution—Using UserFunctions, Step 4

A solution for step 4:

Hint: Notice the Call AddNoise and Formula objects use the global Amplitude, so both of the objects need to run after the Set Amplitude object executes. Connecting the Sequence pins from Set Amplitude to Call AddNoise, and Call AddNoise to Formula ensure the objects execute in the required order.


Importing and Deleting Libraries of UserFunctions

Build a simple program to import the uflab.vee functions. Call the function that adds the noise, and then delete the library programmatically. Use the Select Function choice in the object menu of the Call object.

Hint: Click on Load Lib in the Import Library object menu to manually load the library you specified, so that you can use the Select Function feature in Call.

Solution—Importing and Deleting Libraries Programmatically

This is a solution for deleting the library programmatically.

Key Points

Select Function:

Notice that this selection will configure the proper input and output pins for the function you select.

Editing UserFunctions:

If you import a library of UserFunctions programmatically, you will not be able to edit them. You can view them and set breakpoints to debug. If you want to edit the UserFunctions you import, use the Merge Library command.

Set Variable Caution:

Notice that when you use a global variable in a function, you have to remember to create that global when using the function in other programs. One of the advantages of explicitly creating inputs and outputs is that they are easier to track.


Creating Operator Panels and Pop-ups

Creating Operator Panels and Pop-ups, Step 1

Create a panel to ask an operator to enter numbers. Create a UserObject to interact with an operator. Ask the operator for 2 inputs, A and B. Send both inputs to a display. Use a UserObject with Show On Execute checked to display the panel.

Solution—Creating Operator Panels and Pop-ups, Step 1

The following figure is a solution in detail view.

This is the panel that appears when the program runs.

Key Points

UserObject Properties:

In the UserObject Properties dialog box, select Pop-Up Panel and click to turn on Show Panel On Execute. Change the Pop-Up Panel [image] Panel Title name to “Enter A or B.”

Creating Operator Panels and Pop-ups, Step 2

Instead of displaying both A and B, ask the operator whether to display A or B if the two numbers are different. After asking for the two values, if the values A and B are equal, display the value. If the two values A and B are different, ask the operator to pick a value to display. Display A or B depending on the operator’s choice.

Hint: Add another UserObject with a pop-up panel that is set to Show Panel on Execute, and ask the operator for the value there.

Solution—Creating Operator Panels and Pop-ups, Step 2

This is the UserObject that asks the operator to make a choice when A and B are different numbers.

The second pop-up panel that appears to ask the operator whether to display A or B is as follows.

Key Points

Gate:

The Gate object only sends a value if the two numbers are equal.

Junction:

The JCT object allows multiple inputs to the object Alphanumeric. The JCT object is a “wired OR” object.

List Object as a Menu:

Note the use of the Data [image] Selection Controls [image] List object edited for two choices and formatted for a list. This configuration will output a text A or B. If you need the ordinal value (0 or 1), then use the List object's ordinal data output instead.

Creating Operator Panels and Pop-ups, Step 3

If the operator does not enter numbers, generate an error message. On the second UserObject, which asks the operator to choose whether A or B is displayed when the two numbers are different, add an error. If the operator does not choose A or B within 10 seconds, generate the error.

Solution—Creating Operator Panels and Pop-ups, Step 3

Here is the UserObject modified to generate an error if the operator does not choose A or B in 10 seconds.

Key Points

Exit UserObject:

If the user responds in under 10 seconds, this object will exit the UserObject, even though the Delay object may not have finished executing.

Delay and Raise Error:

After 10 seconds the Delay object pings the Raise Error object, which will pause execution of the program and display the Error Message you have typed in. A red outline will also appear around the object that caused the error, which goes away when you click on the Stop or Run buttons on the main menu bar.

OK and Delay:

Notice the two threads in AnotB are separate, so that the OK and Delay are both running concurrently.


Moving Data To and From Files

Create a VEE program to write the time of day to a file. Generate 100 random points and write them to the file. Calculate the mean and standard deviation of the numbers and append them to the file in the following format:

Mean: xxxxxx

Std Dev: yyyyyy

Next, read only the mean and standard deviation from the file.

Solution—Moving Data To and From Files

This is a solution for moving data to and from files.

Key Points

Generating an Array:

Use randomize(ramp(100,0,1), 0, 1) in the Formula object to create an array of 100 random numbers. The ramp() function generates an ordered array and delivers it to the randomize() function, which then generates random values between 0 and 1.

Time Stamp:

The now() function is used in the expression field of the I/O Transaction dialog box for transaction one in the To File object. When you change the format to TIME STAMP FORMAT, the dialog box displays additional buttons to specify how the time will be stored.

Storing Two Values in a Line:

In both the third and fourth transactions in the To File object, a constant Text string is stored, followed by a Real value. For example, in the third transaction you type "Mean: ",B in the expression field of the I/O Transaction box (assuming the mean value will be on the B input pin).

Extracting a Value From a File:

To get to the mean and standard deviation, first send an EXECUTE REWIND to position the read pointer at the beginning. Then use NULL with the proper format to READ past the time stamp and real array. (This will throw away the values read instead of putting them in an output terminal.) Finally, read the last two lines in the file as strings.

Junction:

Use the Flow [image] Junction object to connect more than one output to a single input, such as connecting the mean and sdev outputs to the Logging AlphaNumeric display.


Manipulating Records

Manipulating Records, Step 1

Build a record with three fields holding an integer, the time right now as a string, and a four element array of reals. The fields should be named int, daytime, and rarry, respectively. Merge this record with another that holds a random number between 0 and 1, and a waveform. Name these fields rand and wave.

Solution—Manipulating Records, Step 1

The resulting record should have five fields.

Key Points

Time Stamp:

Use the now() function within the To String object to create your time stamp for this program. Then you can specify the format.

Configuring a Data Constant as an Array:

Any data type in the Data [image] Constant menu can become an array by selecting Properties, then under Configuration choose 1D Array. The size may be entered here, or as you are typing in the values an Enter will keep appending values.

Naming Fields:

By renaming the input terminals on the Build Record object, you can give your record specific field names such as int, rand, and wave.

The Default Value Control Input:

A Record Constant makes an excellent interactive display object by adding a Default Value Control pin. The Record Constant will automatically configure itself for the record it receives.

Manipulating Records, Step 2

Use a conditional expression in a Formula object to test the random value in the record, and display either the value or a text string. If the value is less than 0.5, display that random value; otherwise, output a text string “More than 0.5." Next, extract only the time and the waveform.

Hint: Do not use a Formula object to extract the time and waveform. Display this record with an AlphaNumeric object.

Solution—Manipulating Records, Step 2

Manipulating records, step 2, is as follows.

Key Points

Using a Conditional Expression:

VEE supports a conditional expression, which provides an efficient way to implement an if-then-else action. The conditional expression in this Formula object is known as a triadic. It is (a.rand < 0.5? a.rand: "More than 0.5"). Notice that it is all one expression, and you can write it with line breaks in the Formula object as shown. If there were more than one expression in the Formula object, the expressions would be separated with semi-colons (;).

The Sub Record Object:

Notice the Text array of the fields on the Sub Record input pin labeled fields. When you configure the Sub Record object to include fields, it will output a record that only contains the fields specified.

Manipulating Records, Step 3

Replace the integer input for the first field with a For Count object and step through 10 iterations. Be certain to “ping” the random number generator and the time function on each iteration. Send the complete record into a To DataSet object. In a separate thread, retrieve all records from the dataset where the random value is greater than 0.5. Put the resultant records into a record constant

Hint: You'll need a control pin for a Default Value on the Record Constant object.

Solution—Manipulating Records, Step 3

A solution for manipulating records, step 3, is shown below.

Key Points

The To DataSet Object:

The Clear File at PreRun option only clears the file before data is sent the first time. Notice that the program sends 10 different records to the same file sequentially, and they are appended to the file.

The From DataSet Object:

This object is configured to retrieve all records where the rand field is greater than 0.5. In this case, five out of ten records meet that criterion and the first record is shown with an index number of 0.


Test Sequencing

Using the Test Sequencer, Step 1

Create a simple UserFunction called UpperLimit that is a pop-up panel with a Real64 Slider and a Confirm (OK) object. Send the output of the slider to a global variable called UpLimit and also to an output terminal. Create a Sequencer object, and configure test1 in the Sequencer as an EXEC transaction that calls UpperLimit.

Create another function called AddRand that simulates the test you might call. This function should add an input value to a random value (0 to 1). It will have one input pin and one output pin.

From the Sequencer, create test2 to call AddRand and send in a zero. Test the return value to do a limit comparison less than the global UpLimit value. If it passes, then return "PASS" + test2.result. If it fails, return "FAILED" + test2.result. Put an Alphanumeric display on the Return pin of the Sequencer.

After the Sequencer object, ping a Get Variable object (UpLimit) and another Alphanumeric display. Run the program several times.

Solution—Using the Test Sequencer, Step 1

This is a solution for the first step of using the Sequencer.

Key Points

Setting Global Variables with a UserFunction:

A typical use of the first Sequencer transaction is to call a UserFunction that sets the Global Variables, as it does in this case. Then you can utilize these variables in any test that follows, as is shown here.

The Sequencer Return Pin:

The Return pin in this example delivers a PASS or FAIL message plus the test value. You could use this pin to deliver any message or value from a particular test.

Using the Test Sequencer, Step 2

Disable the first test. Assuming that you do not need the global anywhere else, you can call the UpperLimit function directly. Change test2 so that it compares the return value of AddRand(0) against the result of the UpperLimit function.

Hint: For disabling the first test, use the Sequencer Transaction box as follows.

Note that in above figure, the first test in the Sequencer is “commented out” with two slashes to show that it is disabled.

Solution—Using the Test Sequencer, Step 2

A solution to using the test Sequencer, step 2, is as follows.

Key Points

The UserFunction in an Expression Field:

In this example, instead of comparing a test result to the UpLimit variable, you can type the function name UpperLimit() in the expression field where the variable would go.

Using the Test Sequencer, Step 3

Edit the test2 Sequencer transaction that calls the VEE function random (0,1). Compare the result against a limit less than 0.5. Cut and paste the test1 transaction until you have a total of four tests.

Build a program to run the Sequencer five times. Record the data in a data set of records and collect the data in an array. Using the array, find the minimum, maximum, mean, and standard deviation of the results of the second test.

Solution—Using the Test Sequencer, Step 3

A solution to Step 3 is as follows.

Key Points

The Data Format for Several Runs of the Sequencer (First Thread):

When the Sequencer executes once, it outputs a Record of Records. The first record has field names that match the test names, then each field holds a record containing the different pieces of data for that particular test. When the Sequencer runs several times, each Record of Records can be added to an array, which can then be investigated. If you use the <record>[*].<record>.<field> format in the Formula object, you will get an array of data. In this case, you get an array of real values giving the test results for five runs of test2. You can then calculate the minimum, maximum, mean, and standard deviation from this array. You could specify a single run of test2 by indicating a particular element in the array of records of records. For example, to get the first run result of test2 you would use the expression: A[0].test2.result.

Using the Test Sequencer, Step 4

Add a timestamp field to the logging record. Add a delay so that each step runs one second apart. In a separate thread, get all the results of test2 and send them to a record constant.

The Delay Object (First Thread):

This object holds execution flow for the specified number of seconds. Here it is used to ensure the time stamp values vary between each run of the Sequencer.

Adding a Time Stamp:

To add a time stamp, open the Sequencer object menu and select Properties [image] Logging tab to check Record Fields to Log [image] Time Stamp. The Properties [image] Logging tab dialog is as follows.

Solution—Using the Test Sequencer, Step 4

A solution to step 4 of using the test sequencer is as follows.

Hint: To display a record, click on the Record [image] Record: Scaler field for one of the tests and the Record Field Data dialog box appears. The Record Field Data dialog box is shown below.

Using the Test Sequencer, Step 5

Print the time stamp fields from the records on a Logging Alphanumeric display.

Hint: Use four Formula objects (one for each test). To show all four Formula results in one Logging Alphanumeric display, add a Junction object. Use a To String to format the 63G time stamp value into a more readable string.

Solution—Using the Test Sequencer, Step 5

Following figure is the program thread to print the time stamps to a display, step 5 of using the test sequencer.

Key Points

Converting Time Stamp Formats:

The To String object before Logging AlphaNumeric converts the time stamps from a Real format to a Time Stamp format for more clarity.

Using the Test Sequencer, Step 6

If the Sequencer includes many tests, it can become cumbersome to use many individual Formula objects connected to a Junction. Instead, you can use a Formula that contains an expression, generate the expression at run time, and loop through the possible expressions.

First the example will generate the expression strings.

In a separate thread, use a Loop and a Formula to generate a test expression string. Output the information as a string in a Logging Alphanumeric. The string generated in the Formula should be "a[*].test<x>.timestamp" where <x> goes from 1 to 4.

Solution—Using the Test Sequencer, Step 6

A solution for step 6 is:

Using the Test Sequencer, Step 7

Now take the Loop and the Formula you built in Step 6, and replace the four Formulas and Junction in the previous step with the Loop and Formula. Plus, you now want to evaluate the string you built. Send the string generated (the expression "a[*].test<x>.timestamp") into a Formula to be evaluated at runtime.

Formula Control Pin on the Formula Object:

The Formula you want to evaluate is generated by the Formula inside the Loop. You can create a second Formula box with a control input for its Formula expression. The expression the second Formula evaluates is generated at runtime.

Solution—Using the Test Sequencer, Step 7

One solution to step 7 is:

Key Points

• The To String object is still being used to format the Real64 into a time stamp format.

• Notice the sequence line between the first "generate" Formula and the second "evaluate" Formula. This ensures the second Formula will not execute until it gets the new string to evaluate.

Using the Test Sequencer, Step 8

Display only the records in which test 1 passed and test 2 failed.

Solution—Using the Test Sequencer, Step 8

A solution to the final step in using the test sequencer is as follows.

Key Points

The EOF Pin on the From Data Set Object (Second Thread):

The EOF pin is added in case there are no records that fit the criteria. If this happens then the EOF pin will fire, instead of VEE halting the program with an error message.

The Conditional Expression in the From Data Set Object (Second Thread):

The expression is (Rec.test1.pass==1) OR (Rec.test2.pass==0), with the same <record>.<record>.<field> format. Rec is the name of each record in the dataset as it is read and tested. Test1 and test2 specify which tests VEE should examine, and the field name pass is the default name for the pass-fail indicator (1 or 0) assigned by VEE. (You enable or disable different fields for all tests by selecting Logging tab in the Sequencer Properties box.)


Guide to VEE Example Programs

This guide summarizes the example programs shipped with Agilent VEE Pro. These examples demonstrate useful programming techniques, and are divided into the categories listed below.

Click on a category to see a list of programs and their summaries. The button shown with each VEE program opens it in a new VEE window.

Examples | Description
.NET Examples | Multiple .NET examples demonstrating .NET's power and flexibility. Rated by difficulty.
ActiveX Controls | A short list of ActiveX examples that show the use of some typical ActiveX controls.
Analysis | A list of examples that demonstrate VEE's data analysis capabilities.
Electrical Applications | A short list of examples that demonstrate building and unbuilding time-domain waveforms, a DS1 Pulse Template test simulation, and lissajous pattern generation.
Dynamic I/O Configuration | A short list of examples that demonstrate the use of VEE in finding instruments either local or remote.
Excel Library | Multiple examples showing the use of the Excel Library to transfer data to and from Excel, format Excel cells, and draw Excel graphs.
Financial Applications | A short list of common financial calculations including NPV, payback, and future value.
Games | A list of games that highlight basic and advanced VEE features in a fun way.
Instrument Manager Integrated Examples | A list of examples integrated in the Instrument Manager.
Instrument Measurements | Multiple examples showing how to perform a broad variety of instrument measurements. Over a dozen instruments are used.
IVI Driver Example | A short list of IVI examples using a Power Meter and Spectrum Analyzer.
Manufacturing Applications | An example that demonstrates how VEE might be used in a manufacturing application. Numerous VEE objects are demonstrated as well as sequencing.
MATLAB Script | A list of examples using MATLAB to highlight how MATLAB can extend the power of the VEE application.
Mechanical Applications | A short list of examples that demonstrate mechanical engineering problems used to exhibit VEE features.
Microsoft Access | A short list of examples using ActiveX to interact with Access. Moves data to a database and displays it.
Microsoft Excel | A short list of examples using ActiveX to interact with Excel. Insert random data, an array of data, and chart data.
Microsoft Outlook | A short list of examples using ActiveX to interact with Outlook. Send email.
Microsoft Word | A short list of examples using ActiveX to interact with Word. Insert data and a bitmap, search and replace, and do a mail merge.
Old VEE RPC API | A library of old VEE remote procedure calls.
Programmatic Properties | Multiple examples of using Programmatic Properties
VEE Lib Examples | Multiple examples of the VEE Lib directory's offerings.
VEE Programming Concepts | Multiple examples of using VEE objects to demonstrate VEE capabilities. Extensive, comprehensive, and instructional.
Visual Basic | An example that synthesizes a pulse and then displays the pulse with test limits.
VB Script | A short list of examples that demonstrate various uses of VB Script. DS1 pulse test, callable VEE server information, etc.
Visual C++ | An example demonstrating a DS1 pulse test.
Windows Forms Controls | Multiple examples of Windows Forms Controls being used in VEE.

Note

Examples in the examples\Manual directory are not listed here since they are discussed in other VEE Help topics, and in the VEE manuals.


Renamed Example Files

VEE 6.0/6.2 | VEE 7.0 | VEE 7.5
Access97DataClient.vee | Access97DataClient.vee | AccessDataClient.vee
Access97Enumerate.vee | Access97Enumerate.vee | AccessEnumerate.vee
Excel97Graph.vee | Excel97Graph.vee | ExcelGraph.vee
Excel97a.vee | excela.vee | ExcelInsertData.vee
Excel97b.vee | Excel97b.vee | ExcelInsertArrayData.vee
 | Excela UFunction.vee | ExcelUFunction.vee
 | Excel97a UFunction Lib.vee | ExcelUFunctionLib.vee
Excel97Weather.vee | Excel97Weather.vee | ExcelWeather.vee
 | LabVIEW.vee | LabVIEW.vee
Outlook97.vee | Outlook97.vee | OutlookSendMail.vee
Word97.vee | Word97.vee | Word.vee
Word97DataSheet.vee | Word97DataSheet.vee | WordDataSheet.vee
Word97MailMerge.vee | Word97MailMerge.vee | WordMailMerge.vee


.NET Examples

Microsoft .NET Examples

Example Name

Description

Referenced Assemblies/
Namespaces/Classes

Difficulty

ComputingHash.vee

Demonstrates how to compute a hash of the contents of a VEE record. The VEE record and the hash are saved out to a file. The file is then re-read. The hash is recomputed on the record that is extracted from the file and then compared to the hash stored in the file. This is a simple way to verify the contents of the file are intact.

Assemblies: mscorlib

Namespaces: System. System.Text, System.Security.Cryptography

Classes: System.Security.Cryptography.SHAManaged, System.Text.Encoding

3

DatabaseReadUsingDataset.vee

Demonstrates how to use the OleDbConnection, OleDbAdapter, and the Dataset classes to create an in-memory copy of several database tables.

Assemblies: mscorlib, System.Data

Namespaces: System, System.Data, System.Data.OleDb

Types: System.Data.OleDb.OleDbConnection, System.Data.OleDb.OleDbAdapter, System.Data.Dataset

2

DatabaseReadUsingOleDbReader.vee

Demonstrates how to use the OleDb connection, command and data reader classes to query information from an Access database file.

Assemblies: mscorlib, System.Data

Namespaces: System, System.Data, System.Data.OleDb

Types: System.Data.OleDb.OleDbConnection, System.Data.OleDb.OleDbCommand, System.Data.OleDb.OleDbDataReader

2

DateTime.vee

Demonstrates the built-in DateTime functions in the .NET Framework, e.g., getting the current date and time, getting the day of week, getting the year, querying whether its a leap year, etc.

This is also a good example to see how static and instance members are mixed together and invoked from VEE. The System namespace is imported to save some typing.

Assemblies: mscorlib

Namespaces: System

Classes: System.DateTime, System.DayOfWeek

1

DateTimeConversion.vee

Demonstrates how to convert between .NET DateTime and VEE time. It also shows an example of using the new asClrType type conversion function. Note that with .NET's DateTime class, it is easy to convert UTC time to local time. The System namespace is imported to save some typing. Also, every object in .NET has at least one ToString method to produce nicely formatted print of the object information; this example shows how powerful it can be.

Assemblies: mscorlib

Namespaces: System

Classes: System.DateTime

2

DeleteDir.vee

Demonstrates how easy it is to query whether a directory exists, create a deep directory hierarchy and recursively delete it. This tiny example serves as an introduction to the many easily accessible file system management functions in the .NET Framework. See FileOperations.vee for a larger number. For an overview, browse the class under the System.IO namespace. Also, see MSDN for more details.

Assemblies: mscorlib

Namespaces: System.IO

Classes: System.IO.Directory

1

DiskInfo.vee

Demonstrates how to get the size and free space of your disk. This used to a non-trivial task involving importing kernel32.dll and invoking the Win32 API call. Compare this example with examples\contrib\Win32\kernel32.vee. This example also queries a lot of other disk information. See the UserFunction show_all_diskproperties. This is also a good example to see how to access and enumerate .NET collections.

Assemblies: mscorlib, System.Management

Namespaces: System, System.Management

Classes: System.Management.ManagementObject

3

DrawOnBitmap.vee

Demonstrates how to create a bitmap of the desired size and type. You can then draw on it using the System.Drawing.Graphics object. The resulting bitmap is saved to the specified file and then the VEE picture object is used to display the bitmap. There are two key concepts in this example. The first is getting a "Graphics" object from the bitmap using the static method System.Drawing.Graphics.FromImage() method. The Bitmap class derives from the System.Drawing.Image class, so an instance of a bitmap can be passed to this function. Once you have a graphics object, you can draw pretty much anything you want on it. The second key concept is to Dispose of any drawing objects that are explicitly created. In this example, the Graphics object created by calling FromImage, the font that was created as well as the Bitmap object are all disposed. Failure to do so can cause the VEE program to consume too many GDI resources and adversely affect program performance.

Assemblies: mscorlib, System.Drawing

Namespaces: System.Drawing, System.Drawing.Imaging

Classes: System.Drawing.Bitmap, System.Drawing.Graphics, System.Drawing.Font, System.Drawing.Brushes, System.Drawing.Pens, system.Drawing.Imaging.PixelFormat, System.Drawing.Imaging.ImageFormat

3

Environment.vee

With .NET Framework, it is easy to get information about your program environment, e.g., the current directory, the command line, the machine and user name, etc.

This is also a good example to see how static members are invoked from VEE.

Assemblies: mscorlib

Namespaces: System

Classes: System.Environment

1

EnumboundtoSelectionControl.vee

Demonstrates how to populate a VEE selection control like a drop-down list with all the enumeration values in a .NET enumeration and the convert it back.

Assemblies: mscorlib

Namespaces: System

Classes: System.Enum

1

EnumerateEnums.vee

Demonstrates some interesting things that you can do with .NET Enumerations. This example gets the type of System.FileAttributes, iterates through the enumerations defined in that type, and prints out the textual and numerical values of those enumerations. The example is designed generically enough that you can apply the EnumNamesAndValues user function on any .NET Enum types, not just the System.FileAttributes type.

Assemblies: mscorlib

Namespaces: System

Classes: System.Enum, System.FileAttributes

3

FileInfo.vee

Demonstrates how easy it is to obtain attributes of a file, e.g., the creation time, the last access time, the file length and whether it is read-only. Note that System or System.IO namespaces are imported to save some typing.

This IsFileReadOnly user function also shows how you would do bit operations on .NET Enums and how you can convert a .NET type to another .NET type using the System.Convert class.

Assemblies: mscorlib

Namespaces: System, System.IO

Classes: System.Convert, System.FileInfo, System.FileAttributes

2

FileOperations.vee

Demonstrates VEE 7.5's use of the .NET Framework's File and Directory classes. First, it gets the special Personal Folder directory which is usually under "document settings\username"; it then creates a deep directory hierarchy under the personal folder if it doesn't already exist; it then creates a text file there and writes a formatted line to the file; finally it opens the file for reading. This also demonstrates how to get all the logical drives on your machine.

Assemblies: mscorlib

Namespaces: System.IO

Classes: System.IO.Directory, System.IO.File, System.IO.Path, System.IO.StreamWriter

2

GetStockQuote.vee

Demonstrates how to get stock quotes with only 10 lines of code. Just type in the ticker symbol for your favorite stock and you get the 20 minute delayed quote back.

This example shows some powerful things that you can do with the .NET Framework, e.g., web request and response, reading a stream, string matching via regular expressions, etc.

Assemblies: mscorlib, System

Namespaces: System.Net, System.IO, System.Text.RegularExpressions

Classes: System.Net.WebRequest, System.Net.WebResponse, System.IO.Stream, System.IO.StreamReader, System.Text.RegularExpressions.Regex

3

HashTable.vee

Demonstrates one of the built-in data structures in .NET Framework. A hash table is a collection of key and value pairs organized based upon the hash code of the key. A Hash table allows a more efficient search algorithm than an Array does. You can store any type of objects based on any type of key as long as the key implements a couple of methods (GetHashCode and Equals). This example shows how to add the key and value pairs, get the number of items stored, find out whether a key exists in the hash table, do a search based on a key, etc.

Assemblies: mscorlib

Namespaces: System.Collections

Classes: System.Collections.Hashtable

1

IPAddress.vee

Demonstrates how to easily get the IP address of your machine (or any machine). This example also shows how to access a .NET object array using the GetValue Array method.

Assemblies: mscorlib, System

Namespaces: System.Net

Classes: System.Net.Dns, System.Net.IPHostEntry, System.Environment, System.Array

1

PasswordManagement.vee

Demonstrates how to create a simple user name and password login system.

Assemblies: mscorlib

Namespaces: System, System.Security.Cryptography

Types: System.Security.Cryptography.SHA1CryptoServiceProvider, System.Convert

2

ProcessInfo.vee

Demonstrates how easy it is to get information about a process like its virtual memory size, total processor time, handle count, priority, start time, number of threads, thread ids, thread states and thread priorities.

Assemblies: mscorlib, System

Namespaces: System, System.Diagnostics

Classes: System.Diagnostics.Process, System.Threading.Thread

2

Registry.vee

Demonstrates how to use the .NET Framework classes to access your registry. This used to be a non-trivial task involving importing advapi32.dll and invoking some hard to understand WIN32 API calls. Compare this example with examples\contrib\advapi32.vee.

Assemblies: mscorlib

Namespaces Microsoft.Win32

Classes: Microsoft.Win32.Registry, Microsoft.Win32.RegistryKey

1

SelectFiles.vee

Demonstrates how to use one of the built-in common dialogs in the .NET Framework. In this example, the OpenFileDialog class is used to display a Windows standard open file dialog box, but you could just as easily use others like SaveFileDialog, PrintDialog, ColorDialog, FontDialog, etc. You can still use VEEs File Name Selection dialog box, but you can get more flexibility with .NETs OpenFileDialogBox. For example, you can turn on multi-selection of files easily.

Assemblies: System.Windows.Form

Namespaces: System.Windows.Form

Classes: System.Windows.Forms.OpenFileDialog

1

SelectFolder.vee

Demonstrates how to select a folder without selecting a file.

Assemblies: mscorlilb

Namespaces: System, System.Windows.Forms

Classes: Systems.Windows.Forms.FolderBrowserDialog, System.Environment.SpecialFolder

1

Sendmail.vee

Demonstrates how easy it is to send an email with .NET Framework. This example accomplishes the same result as the lib\SmtpMail.vee example with a lot less work. With .NET, you can send an email from your VEE program with eight lines of code or less.

Assemblies: System.Web

Namespaces: System.Web.Mail

Classes: System.Web.Mail.SmtpMail

2

SendMailWithAttachments.vee

Demonstrates how easy it is to send mail with attachments using .NET.

Assemblies: System.Web

Namespaces: System.Web.Mail

Classes: System.Web.Mail.SmtpMail

1

SpecialFolders.vee

Demonstrates how to get the paths of all kinds of special folders on your machine. This used to be a non-trivial task involving importing shfolder.dll and invoking Win32 API calls. Compare this examples with examples\contrib\win32\shfolder.vee.

Note that the namespace is imported.

Assemblies: mscorlib

Namespaces: System

Classes: System.Environment, System.Environment.SpecialFolder

1

Stack.vee

Demonstrates one of the built-in data structures in the .NET Framework. A stack is a last-in first-out collection, which is in contrast to a queue which is a first-in first-out collection. This example shows how to add (push) objects to the stack and remove (pop) them.

Assemblies: mscorlib

Namespaces: System.collections

Classes: System.Collections.Stack

1

StringOperations.vee

Demonstrates various string operations using .NET methods.

Assemblies: mscorlib

Namespaces: System

Classes: System.String

1

StringSplit.vee

Demonstrates how to split a string into multiple strings using any number of delimiters.

The .NET System.String class has many useful functions. While VEE converts .NET String to VEE Text automatically, sometimes you may want to use the String as a .NET object in order to use its many functions. This example shows how to convert a VEE Text to .NET String. It also shows how to convert an array of VEE Text to an array of .NET System.Char.

This is a good example to see how to use the new AsClrType type conversion function.

Assemblies: mscorlib

Namespaces: System

Classes: System.String, System.Char

2

TextEncodedBInary.vee

Demonstrates how to use the .NET Framework classes to encode binary data as text using Base64 and then convert the Base64 text encoded binary back to binary form. You can use this technique to send binary data in a text email if you didn't have access to file attachments.

Assemblies: mscorlib

Namespaces: System

Classes: System.Convert

2

TimeZone.vee

Demonstrates how to use the System.TimeZone object.

  • Getting the UTC offset of the current time

  • Determining if a time is in Daylight Savings Time

  • Getting the name of the Daylight Savings Time period

  • Getting the name of the standard time period

  • Getting the start and end times of Daylight Savings time

Assemblies: mscorlib

Namespaces: System, System.Globalization

Classes: System.TimeZone, System.Globalization.DaylightTime

1

UsingTemperatureWebService.vee

Demonstrates how to use a Web service for VEE.

Assemblies: TemperatureService

Namespaces:

Classes: TemperatureService

2

UsingTerraServerWebService.vee

Demonstrates how to use a Web service for VEE.

Assemblies: mscorlib, TerraService

Namespaces: System, Agilent.VeeExample

Classes: TerraService, Place, TileId

2

WhichOS.vee

Demonstrates how to get the version and platform of your operating system.

The README details the steps to reproduce the example.

Assemblies: mscorlib

Namespaces: System

Classes: System.Environment, System.OperatingSystem

1

WriteEventLog.vee

Demonstrates how to use the System Menu's Write to Event Log entry object to log VEE error information to the Application event log and then read those entries back out of the log.

Assemblies: mscorlib, System

Namespaces: System.Diagnostics

Types: System.Diagnostics.EventLog

1

XmlReadingUsingXmlTextReader.vee

Demonstrates how to read XML via a System.IO.StringReader.

Assemblies: mscorlib, System.Xml

Namespaces: System, System.IO, System.Xml

Types: System.IO.StringReader, System.Xml.XmlTextReader

2

XmlSearchingUsingXPathNavigator.vee

Demonstrates how to read XML into an XPathDocument and then create an XPathNavigator .

Assemblies: mscorlib, System.Xml,System.Xml.XPath

Namespaces: System, System.IO, System.Xml, System.Xml.XPath

Types: System.IO.StringReader, System.Xml.XPath.XPathDocument, System.Xml.XPath.XPathNavigator, System.Xml.XPath.XPathNodeIterator

2

*Difficulty Level is numbered from 1 to 3, 1 being the easiest and requiring the least amount of .NET and VEE experience.


.NET Controls Examples

Example Name | Description | Referenced Assemblies/ Namespaces/Classes
Button.vee | Demonstrates the use of a Windows Forms Control Button | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: Button
CheckBox.vee | Demonstrates the use of a couple of Windows Forms controls, GroupBox and CheckBox. This example also demonstrates how to build a composite control using other controls. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: GroupBox and CheckBox
CheckListBox.vee | Demonstrates the use of a couple of Windows Forms controls, CheckListBox and Label. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: CheckedListBox and Label
ComboBox.vee | Demonstrates the use of a couple of Windows Forms controls, ComboBox and Label. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: ComboBox and Label
ContainerControl.vee | Demonstrates the use of a couple of Windows Forms controls, DataGrid and ContainerControl. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: DataGrid and ContainerControl
CustomCounter.vee | Demonstrates a custom control. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms
CustomFolderTreeView.vee | Demonstrates a custom control. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms
CustomGrid.vee | Demonstrates a custom control. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms
CustomProgressBarImage.vee | Demonstrates a custom control. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms
DataGrid.vee | Demonstrates the use of a couple of Windows Forms controls, DataGrid and ContainerControl. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: DataGrid and ContainerControl
DateTimePicker.vee | Demonstrates the use of a couple of Windows Forms controls, DateTimePicker and Label. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: DataTimePicker and Label
DomainUpDown.vee | Demonstrates the use of the DomainUpDown control. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: DomainUpDown
GroupBox.vee | Demonstrates the use of a couple of Windows Forms controls, GroupBox and RadioButton. This example also demonstrates how to build a composite control using other controls. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: GroupBox and RadioButton
GroupRadioAndCheckbox.vee | Demonstrates the use of three Windows Forms controls, GroupBox, CheckBox, and RadioButton. | Assembly: System.Windows.Forms and System.Drawing Namespaces: System.Windows.Forms and System.Drawing Types: CheckBox, GroupBox, RadioButton and Point
HScrollBar.vee | Demonstrates the use of three Windows Forms controls, HScrollBar, VScrollBar, and Label. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: HScrollBar, VScrollBar, Label
LinkLabel.vee | Demonstrates the use of the Windows Forms control, LinkLabel. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: LinkLabel
ListBox.vee | Demonstrates the use of a couple of Windows Forms controls, ListBox and Label. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: ListBox and Label
ListView.vee | Demonstrates the use of the Windows Forms control, ListView. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: ListView
MenuStrip.vee | Demonstrates the use of the Windows Forms control, Menustrip. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type:MenuStrip
MonthCalendar.vee | Demonstrates the use of the Windows Forms control, MonthCalendar. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: MonthCalendar
NumericUpDown.vee | Demonstrates the use of the Windows Forms control, NumericUpDown. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: NumericUpDown
Panel.vee | Demonstrates the use of the Windows Forms control, Panel. It also demonstrates the creation of a composite control. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: Panel and CheckBox
PictureBox.vee | Demonstrates the use of the Windows Forms control, PictureBox. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: PictureBox
ProgressBar.vee | Demonstrates the use of the Windows Forms control, ProgressBar. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: ProgressBar
RadioButton.vee | Demonstrates the use of a couple of Windows Forms controls, GroupBox and RadioButton. It also demonstrates how to create a composite control using other controls. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: GroupBox and RadioButton
RichTextBox.vee | Demonstrates the use of the Windows Forms control, RichTextBox. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: RichTextBox
Splitter.vee | Demonstrates the use of several Windows Forms controls, Splitter, Panel, TreeView, and ListView. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: Splitter, Panel, TreeView, and ListView
StatusBar.vee | Demonstrates the use of the Windows Forms control, StatusBar. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: StatusBar
TabControl.vee | Demonstrates the use of the Windows Forms control, Tab Control. This example also demonstrates the creation of composite controls as it includes TabPages which include a Button, CheckBoxes, and RadioButtons. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: TabControl, TabPage, Button, RadioButton, and CheckBox
TabPage.vee | Demonstrates the use of the Windows Forms control, Tab Control. This example also demonstrates the creation of composite controls as it includes TabPages which include a Button, CheckBoxes, and RadioButtons. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: TabControl, TabPage, Button, RadioButton, and CheckBox
TextBox.vee | Demonstrates the use of the Windows Forms control, TextBox. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: TextBox
ToolStrip.vee | Demonstrates the use of the Windows Forms control, ToolStrip | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Type: TooStrip
TrackBar.vee | Demonstrates the use of a couple of Windows Forms controls, Label and TrackBar. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: Label and TrackBar
TreeView.vee | Demonstrates the use of a couple of Windows Forms controls, TreeView and Label. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: TreeView and Label
VScrollBar.vee | Demonstrates the use of three Windows Forms controls, HScrollBar, VScrollBar, and Label. | Assembly: System.Windows.Forms Namespace: System.Windows.Forms Types: HScrollBar, VScrollBar, and Label


ActiveX Controls
examples\ActiveXControls

The ActiveX controls listed here must be installed on your system before the programs will run properly.

1. ActiveMovie Control

2. Microsoft Common Dialog Control

3. ListView Control

4. ProgressBar Control

5. Microsoft RichTextBox Control

Additionally, VEE requires Microsoft Office 2000 or later for the use of ActiveX automation.

ActiveX Control Examples
 | Example Name | Description
1 | ActiveMovie.vee | Demonstrates how to use the ActiveMovie control to display a movie file.
2 | CommonDialog.vee | Demonstrates the use of several Windows common dialog boxes as implemented in the Common Dialog ActiveX control.
3 | ListView.vee | Demonstrates the use of the ListView control provided by comctl32.ocx.
4 | ProgressBar.vee | Demonstrates the use of the ProgressBar control provided by comctl32.ocx.
5 | RichTextBox.vee | Demonstrates how to get RTF text into the RichTextBox control, then save that text in a VEE program to avoid distributing a separate .rtf file with your program.

See Also

Releasing ActiveX References


Analysis
examples\Analysis

Analysis Examples
Example Name | Description
AnalogFilter.vee | Shows how to display the transfer function of a filter, and how to use array math rather than iterators.
curvefit.vee | Illustrates various regression methods to perform curve fitting.
magDist.vee | Demonstrates magDist() function generating a histogram of data point distribution.
mixer.vee | demonstrates how to: Simulate signals using the Virtual Source. Obtain information from a sophisticated data structure.
psk.vee | Illustrates the use of many objects in unconventional ways to implement a message encoding/decoding scheme.
ReadMarkerValues.vee | Demonstrates a pair of UserFunctions that set markers on an XY Trace display, then read the values back out.
setmap.vee | Shows how to retrieve meaningful information from a Spectrum data type using the Data [image] UnBuild Data [image] Spectrum, PComplex, and Data [image] Access Array [image] Set Mappings objects.
traj1.vee | Demonstrates the differences between the Detail and Panel Views in a program that calculates trajectory.
traj2.vee | Demonstrates the Show Panel on Execute mode for UserObjects to display data as requested.
xfftfunc.vee | Performs FFT on a waveform using the ScaleFFT UserFunction.


Electrical Applications
examples\Applications

Electrical Application Examples
Example Name | Description
digfilt.vee | Illustrates the following: Unbuilding and building time-domain waveforms. Construction of a 3rd order elliptical digital filter. Automatic conversion from the time domain to the frequency domain.
telecomm.vee | Simulates a DS1 Pulse Template test using previously stored waveform data. A common measurement in the telecommunications field monitors the pulse shape from a DS1 test fixture. This program illustrates how to automate the waveform template matching to a measured DS1 pulse.
lissajou.vee | Demonstrates lissajous pattern generation using two waveform inputs to an X vs Y Plot display object.
pid.vee | Shows a simple Proportional-Integral-Derivative controller for closed-loop process control.


Dynamic I/O Configuration
examples\InstrumentIO

Dynamic I/O Configuration Examples
Example Name | Description
DynamicFindDMM.vee | Can find either the first digital multimeter or all DMMs on your system.
DynamicFindInstruments.vee | Finds all GPIB and VXI instruments on your system, and returns their model names and bus addresses. The instruments must be IEEE 488.2 compliant and must understand the "IDN?" command.
DynamicFindInterfaces.vee | Reports the type and logical unit number of all instrument interfaces on your system.
DynamicFindRemoteInstruments.vee | Finds all instruments available on the specified remote host. The remote host must have Agilent VEE installed for remote discovery to work.
PreRunDeviceCheck.vee | Demonstrates some of the instrument configuration checking features available during VEE's pre-run phase.


Excel Library
examples\ExcelLibrary

Excel Library Examples
Example Name | Description
AddComment.vee | Demonstrates how you can add a comment to cell.
AlphaColAndNumericCol.vee | Computes the column name from an equivalent numeric input from 1 to 256.
BarChart.vee | Creates a Bar Chart in Microsoft Excel.
ColoredLimits.vee | Demonstrates how to change text colors depending upon limits.
CreateVbaMacro.vee | Creates and executes a simple VBA macro.
DataFromCells.vee | After selecting a workbook file, data is read from a range in the file and displayed.
DataToCells2D.vee | This example sends 2D data roundtrip to Excel.
DataToCells3D.vee | This example sends 3D data roundtrip to Excel. Data is automatically sent to multiple sheets
EnumerateCharts.vee | Shows the chart names in a workbook.
EnumerateNames.vee | Shows the range names in a worksheet.
EnumerateSheets.vee | Displays the worksheets names within a given workbook.
EvaluateCellFormula.vee | Retrieves the value of a calculation for a single cell.
ExcelVisibleOnTop.vee | Demonstrates how to ensure Excel remains on top when made visible.
FindFirstEmptyRow.vee | Finds the first empty within a range of rows.
FormatCell.vee | Demonstrates the different cell formats.
FormatCellsAllColors.vee | All cell back colors are sent to Excel as text and each cell is formatted with that back colors.
FormatText.vee | Sets the font for an entire range of data.
FormatTextAllColors.vee | Formats all the text in the cells to a given fore color.
IterateColumns.vee | Iterates through a group of columns first to send a data sequence and then again to retrieve the same sequence.
IterateRows.vee | Iterates through a set of rows first to send a data sequence and then again to retrieve the same sequence.
LineChart1D.vee | Creates a one dimensional line chart in Excel.
LineChart2D.vee | Creates a two dimensional line chart in Excel.
LineChart2DLogarithmic.vee | Creates a two dimensional logarithmic line chart in Excel.
Macro.vee | Demonstrates running an existing macro in an Excel workbook.
MergeCells.vee | Describes how to merge several cells together in Excel.
MultipleWorkbooks.vee | Sends a 2D array to Excel repeatedly for multiple new workbooks.
NavigateCells.vee | Calculates a cell address from a relative position and then from an absolute position.
NumericRowColFromCell.vee | Demonstrates how a cell address can be translated into numeric row and column outputs.
OpenSaveAs.vee | Opens a workbook with read-only true and saves it to a new name.
PanelImage.vee | Shows how you can include VEE graphs in an Excel report.
PieChart.vee | Creates a pie chart in Excel.
Print.vee | Prints an Excel Workbook file.
PrintPreview.vee | Displays a workbook in Print Preview mode.
ReUsingCharts.vee | Describes how to use the charting features of Excel and the data management abilities of the Excel Library to create custom charts
SaveAsHTML.vee | Changes the settings so you can save as an HTML file. It also sets the DisplayAlerts settings to False so you can overwrite the SaveAs file as many times as you want.
SearchArray.vee | Searches a one or two dimensional array.
SelectWorkbookAndEnumerations.vee | Illustrates the use of OpenWorkbook, SelectWorkbook, and Enumerate workbooks.
SendColumnByColumn.vee | Sends data to Microsoft Excel column by column.
SendComplexData.vee | Provides one solution for sending Complex as a vertically oriented Cartesian Complex array.
SendCoordData.vee | Creates a vertically oriented SendData for coordinate numbers.
SendPComplexData.vee | Creates a vertically oriented SendData for Polar Complex numbers.
SendRecordData.vee | Sends a record array to a workbook with predefined named ranges in the first Worksheet that match the field names in the record array.
SendSpectrumData.vee | Illustrates how to unbuild a Spectrum data type and send it to Excel with Start, Stop.
SendWaveformData.vee | Illustrates how to unbuild a waveform data type and send it to Excel with TimeSpan and Data in a particular arrangement you can modify to your liking.
SettingABorderOnARange.vee | Sets the border on a range of cells that are embedded within another range of cells.
StringReplace.vee | Given a string, replaces a sub-string within it. Case sensitivity can be considered.
XYChart.vee | Creates an XY chart in Excel.

See Also

Releasing ActiveX References


Financial Applications
examples\Applications

Financial Examples
Example Names | Description
simp_npv.vee | Demonstrates financial calculations using a simple Net Present Value model with no provision for effect of taxes.
payback.vee | Demonstrates financial calculations using a simple Net Present Value "Discounted Payback Period" model with some provision for the effect of taxes.
futValue.vee | Demonstrates financial capabilities of VEE, and shows the future value growth of a principal amount, through graphical curve plotting.


Games
examples\Games

These examples are complete programs that demonstrate a variety of VEE programming techniques.

Game Examples

Example Name

Battleship

BlackJack

Euchre

MineSweeper

Movies

Race

Reversi

Slots

Solitaire

StraVEEgo

Wheel


Instrument Manager Integrated Examples
examples\InstrumentIO\InstrManagerIntegrated

Instrument Manager Integrated Examples
Example Name | Description
Ag33220A_IVI-COM.vee | Download a predefined signal into the 33220A LXI instrument and to output it through the use of its IVI-COM driver
Ag34410a_LXI.vee | Retrieve a measurement from an Agilent 34410A Digital Multimeters (DMM) over LAN
Ag344xxa.vee | Retrieve a measurement from one of the following Agilent Digital Multimeters (DMM): 34401A, 34405A, 34410A, or 34411A
Ag344xxa_Excel.vee | Retrieve 5 measurements from one of the following Agilent Digital Multimeters (DMM): 34401A, 34405A, 34410A, or 34411A. Then the data is programmatically sent to Excel
Ag34980A_IVI-COM.vee | Retrieve the configuration and some data from a 34980A
AgDSO3000.vee | Measure the parameters of a waveform using the DSO3000 family of scopes and VEE Pro's Direct IO functionality
AgDSO603xMSO603x.vee | Retrieve analog data from an Agilent 6000-series DSO or MSO oscilloscope and display it in VEE data display objects
AgDSO603xMSO603x_MATLAB1.vee | Use VEE's embedded MATLAB functions to compute the cross-correlation between analog channels 1 and 2 then display the results
AgDSO603xMSO603x_MATLAB2.vee | Use MATLAB's exp() and abs() functions and the plot function
AgDSO603xMSO603x_MATLAB3.vee | Use VEE's embedded MATLAB functions to filter analog channel 1 through a Butterworth filter then display the result of the calculation
AgE4980a_directIO.vee | Measure the Capacitance and Dissipation Factor using the E4980A LCR meter
AgN1996a.vee | Retrieve a measurement from the Agilent CSA Spectrum Analyzer
AgN19XXA.vee | Configure and control the N19XXA power meter transfer data from the instrument to the PC.
AgN57xx_directIO.vee | Set the outputs and retrieve data from a N5700B modular power supply using Direct IO
AgN57xx_IVI_COM.vee | Demonstrates the use of IVI-COM drivers in VEE 8.0.
AgN67xx_IVI_COM.vee | Use VEE and the IVI COM driver to set the outputs and retrieve data from a N6700B modular power supply
Ag87xxEx.vee | Control the 87XXET/ES in order to retrieve its measurement data
Ag87xx-VNA.vee | Setup multiple traces in a VNA, sweep, download and display data
Ag332x0a1.vee | Download a predefined signal into the generator and output it
Ag332x0a2.vee | Output a AM modulated signal from the generator
Ag661xc-Ag663xb.vee | Programs output, measure output condition, and calculate output power
Ag681x.vee | Makes an Inrush Current measurement
Ag811xx-AgE831x.vee | Configure pulse, pattern, or burst mode
Ag5313xa1.vee | Measure frequency on chan1 and retrieve data
Ag 5313xa2.vee | Measure frequency on chan1 and do data logging
Ag34970a.vee | Identifies cards in frame and plots data
AgE36xx.vee | Set up a voltage sweep, record currents, save to Excel file
AgE44xx.vee | Set up center freq and span, view trace, save to Excel file
AgE44xxCdma2000.vee | Measure occupied bandwidth on CDMA2000, save to Excel
AgE50xxx-ENA1.vee | Setup multiple traces in an ENA, sweep, download and display data
AgE50xxx-ENA2.vee | Setup and calibrate 2-Port S-Parameters using an ECal module
AgE82xx.vee | Setup and calibrate 2-Port S-Parameters using an ECal module
AgE83xxx-AgN52xxx-AgE880xx-Agn338xx-PNA1.vee | Setup multiple traces in a PNA, sweep, download and display data
AgE83xxx-AgN52xxx-AgE880xx-Agn338xx-PNA2.vee | Setup and calibrate 2-Port S-Parameters using an ECal module
AgE443xb.vee | Frequency sweep with SRQ on completion
AgE443xb_Excel.vee | Frequency sweep with SRQ on completion, save to Excel
AgE4438c-AgE8267x.vee | Download waveform to arbitrary waveform generator
AgE4438c-Ag8267x_Excel.vee | Download waveform to arbitrary waveform generator, save to Excel
AgInfiniiumScopeAdvanced1.vee | Display MATLAB cross-correlation
AgInfiniiumScopeAdvanced2.vee | Display Butterworth filter
AgInfiniiumScopeAnalog.vee | Display analog waveform and parameters
AgInfiniiumScopeDigital.vee | Display digital waveform and parameters
AgN33xxa.vee | Programs inputs, measure input conditions, and strip chart
AgN4901b.vee | Auto align and perform BER reading
AgN6700b.vee | Programs outputs, measure output conditions, and strip charts output power
Hp33120a.vee | Set waveform shape, peak amplitude and frequency
Hp34401a.vee | Retrieve the data from a 34401A
Hp34401a_Excel.vee | Retrieve the data from a 34401A and send to Excel
AgU2353a2.vee | Show how to use VEE and the IVI COM driver to generate and retrieve data from a AgU2353A DAQ
AgU2353a1.vee | Show how to use VEE and the SCPI commands to generate and retrieve data from a AgU2353A DAQ


Instrument I/O

Instrument Measurements
examples\InstrumentIO

Instrument Measurement Examples
Example Name | Description
4195imp.vee | Measures the impedance characteristics of a chip type component.
4195net.vee | Is a setup to study the transmission frequency response of a bandpass filter.
4195s11.vee | Measures the Return Loss of a device under test.
4195s12.vee | Measures the Reverse Transmission Coefficients of a device under test.
4195s21.vee | Measures the Forward Transmission Coefficients of a device under test.
4195s22.vee | Measures the Reverse Reflection Coefficients of a device under test.
4195spec.vee | Studies the Harmonic Distortion of a frequency signal with the following parameters: Sweep Start frequency: 5 MHz Sweep Stop frequency: 105 MHz R1 input attenuation: 40 dB S1 source amplitude: -15 dB
4338_ext.vee | Shows how to control the HP 4338A external trigger, and use the instrument drivers sequence output to perform an SRQ and SPOLL, then log readings from the HP 4338A component driver.
8720cal.vee | Shows how the calibration data for an HP 8720C can be stored in a file after the calibration and later on it can be retrieved from the file to dump the cal data to the instrument.
8720lims.vee | Shows the limit segments editing using the HP 8720C and performs the limit line testing on the measured characteristics of the test device.
8720smp1.vee | Performs a phase measurement to study the deviation from linear phase.
8720smp2.vee | Performs phase measurement using an HP 8720C, and the phase value is detected for the selected stimulus frequency. In the second state, Z:Transmission characteristics measurement is done.
8753lims.vee | Shows the limit segments editing using the HP 8753C and performs the limit line testing on the measured characteristics of the test device.
BpTr_STR.vee | Demonstrates stress measurement on a bipolar transistor.
DIOFreq.vee | Finds the frequency response of the HP 3478 multimeter using Direct I/O objects. Needs a HP 3325B function generator and a HP 3478 multimeter.
enum_id.vee | Shows how to use a Selection Control object (Enum) to generate an input for an ID device that uses numbers to select internal states.
hpe1326.vee | Takes readings from the HP E1326. After a delay to take the readings, the readings are uploaded to a file.
hpe1413.vee | Uploads HP E1413 data to a file and then displays the data.
hpe1488a.vee | Takes readings on the HP E1431A, transfers them over the local bus to the HP E1488A, then reads the data over the GPIB to display it on a Waveform display.
hpe1562.vee | Readings are taken on the HP E1413 and transferred directly to the HP E1562 from the HP E1413 FIFO via the VME backplane. Then the readings are read from the HP E1562 and sent by Local Bus to the HP E1488A.
gpibtest.vee | This utility allows you to perform simple GPIB transactions with an instrument.
IC_IB_VB.vee | Displays the hFE values corresponding to IC>1mA and IC<4mA. This is a good example of transistor characteristics and hFE calculation based on the above results.
IC_VCE.vee | Is an example of IC vs VCE characteristics of bipolar transistor.
ID_VDS1.vee | Is a good example of ID-VGS characteristics of MOSFET. It also gives information about Vth@ID=10mA and Vth@MAX(Gm)
ID_VDS2.vee | Is an example of ID vs VGS of MOSFET.
IDfreq.vee | Finds the frequency response of the HP 3478 multimeter using HP Instrument Drivers(HP-ID). Needs a HP 3325B function generator and a HP 3478 multimeter.
cap4291.vee | Can be used for studying: Frequency characteristics of impedance OSC level characteristics of capacitance and dissipation factor Frequency characteristics of capacitance and dissipation factor DC bias voltage characteristics of capacitance and dissipation factor
imp4291.vee | Does Resistance and Reactance Measurement over the frequency sweep from 1000KHz to 1800 MHz.
instr.vee | Shows three methods in VEE for programming instruments.
k2000.vee | Tests the operation of the Keithley 2000 Digital Multimeter.
k2000_dc.vee | Is an example using the Keithley 2000 voltmeter. 100 DCV readings are taken and shown on an XY Trace.
k2001.vee | Tests the operation of the Keithley 2001 Digital Multimeter.
k2001_dc.vee | Sets up the Keithley 2001 to take DC readings using the .01 NPLC Aperture. 100 readings are taken and averaged. Both the average and a plot of the values are shown.
logger1.vee | Shows how to construct a simple multi-channel data logger.
logger2.vee | Shows a data logger that saves measurement data to a file.
loss4291.vee | Can be used for measuring frequency characteristics of relative Permittivity. Channel 1 measures Permittivity real(Er') and channel 2 measures Loss tangent(tan delta).
perm1_91.vee | Is a program for the HP 4291A that measures permeability real for channel 1 measures permeability loss factor for channel 2.
perm2_91.vee | Is used for measuring: Frequency characteristics of relative Permeability OSC level characteristics of relative Permeability DC bias current characteristics of relative Permeability
prmtty_91.vee | Is a program for the HP 4291A that measures permittivity real for channel 1 measures permittivity loss factor for channel 2.
rd126014.vee | Writes the data of "Data Buffer" to port 1 of the Racal Dana 1260-14 and reads it from port 0.
scopeMask.vee | Displays a DS1 mask in the waveform memories of an HP 54502 or HP 54504 oscilloscope. This demonstrates the concept of creating a mask in a scope's waveform memories. Although it builds something that looks like a DS1 mask, the data from which the mask is built does not conform to any standard.
smallsig.vee | Measures small signal gain. This measurement is useful for the study of characteristics of active devices like amplifiers in the linear operating region. This program doesn't include the calibration measurement.
Vdownld.vee | Downloads drivers to the VXI Command Module.
DynamicChangeVisaAddress.vee | This program shows how to change an instrument's VISA address programmatically.
DynamicControlMultiInstruments.vee | Controls a couple of instruments using the dynamic change of VISA interface and address.


IVI Driver Example

AgilentPowerMeterAverages_VEE7.vee

AgilentPowerMeterCalAndZero_VEE7.vee

AgilentSA_VEE7.vee

AgilentSA.vee

Agilent33220.vee


Manufacturing Applications
examples\Applications

Manufacturing Examples

Example Name

Description

mfgtest.vee

introduces some VEE features that you may find useful as you try to build a manufacturing test system. Several VEE features are highlighted, including:

Dialog boxes:
There are several different types of dialog boxes that this example uses. The "login" function makes the heaviest use of them. They are found under the Data [image] Dialog Box menu.

Keyboard drivability:
You may completely control this program by using the Tab key, space bar, and Enter keys in the dialog boxes. Also, there is a custom dialog that allows you to navigate by pressing a function key.

Indicators:
We use several display objects, such as a Color Alarm and Thermometer, to indicate pass or fail conditions in a running test. Indicators are found under the Display [image] Indicator menu.

Picture object:
This object lets you display graphics in a scaleable object. We have used it to display a test connection diagram. It accepts graphics files in Graphics Interchange Format (GIF), Bitmap (BMP), and X Window Dump (XWD) formats. This object is found under the Display menu.

Sequencer status panels:
We have a generic function whose Panel View can be programmatically displayed or hidden. We use this to give a dynamic view of tests as the Sequencer runs.

Sequencer:
The Sequencer has a data pin named ExecTrans that takes an array of test names to execute. By using a multiple-selection list box (one of the Dialog Box objects), you can allow the user of your program to dynamically choose which tests the Sequencer should run.


MATLAB

MATLAB Script
examples\MATLAB

MATLAB Script Examples
Example Name | Description
BasicGraphManipulation.vee | Shows some basic graph and plot manipulation.
FindMaximums.vee | Shows how to locate and highlight graph peaks
Interpolation.vee | Shows the MATLAB Interpl 1D data interpolation function.
Logo3DPlot.vee | Makes an attractive 3D shaded surface plot.
MultiGraphFigure.vee | Shows how to create and display subplots.
MultiTraceGraph.vee | Shows how to plot and color multiple graph traces.
Plot2DArray.vee | Shows how to plot 2D array data from VEE.
SignalProcessing.vee | Introduces the extensive Signal Processing capabilities of MATLAB.
Surf3DPlot.vee | Shows how to create and rotate a MATLAB 3D shaded surface plot.


Mechanical Applications
examples\Applications

Mechanical Examples

Example Names

Description

beam.vee

Demonstrates the use of VEE in a cantilever beam deflection problem. This program uses an XY Trace display to show the deflection of a beam under uniform, ramp, and combined load situations.

chaos.vee

Shows the steady-state value of a simple population model.

coilspr.vee

Demonstrates the calculation of the natural frequency for a coil spring using a number of variable parameters.

convcoef.vee

Demonstrates the use of VEE with a Natural Convection Heat Transfer Model that calculates the heat transfer coefficient, "h", for several body or surface types.

fluidflw.vee

Shows a simple Mechanical Engineering problem setup and solution. It also shows methods of data entry and display, and the use of arrays and global variables for calculating formulas.

torsion1.vee

Shows a simple mechanical engineering problem and solution. It also shows basic data entry and display, as well as the use of a calculation formula.

The program uses a simple formula to calculate the angular deflection of a round torsion shaft, given specified diameter, length, applied torque, and material shear modulus values.

torsion2.vee

Shows a mechanical engineering problem setup and solution. It shows various data entry and display methods, and the use of a calculation formula.

The program uses a simple formula to calculate the angular deflection of a round torsion shaft, given a range of diameters, length, a range for applied torque, and material shear modulus values.


Microsoft Access
examples\ActiveXAutomation

The applications and related ActiveX automation type libraries referenced here must be installed on your system before the programs will run properly.

Microsoft Access Interaction Examples
Example Name | Description
AccessDataClient.vee | Launches Access and stores the test data and the VEE record data into the database file testData.mdb, and then reads it.
AccessEnumerate.vee | Opens the DAO 3.6 (ACCESS) database named testData.mdb, then enumerates (displays all) tables in the database. Next, all fields in the resultsTable are enumerated. This demonstrates that DAO is installed, how to open a database and recordset, use the count and name properties, etc. Note that several "MSys" tables are created by the DAO engine.

See Also

Releasing ActiveX References


Microsoft Excel
examples\ActiveXAutomation

The applications and related ActiveX automation type libraries referenced here must be installed on your system before the programs will run properly.

Microsoft Excel Interaction Examples
Example Names | Description
ExcelInsertData.exe | Uses Excel and ActiveX automation to insert random data into a spreadsheet one cell at a time. It then uses Excel's Average function to calculate the average of the data inserted into Excel.
ExcelInsertArrayData.vee | Uses Excel and ActiveX Automation to insert an array of random data into a spreadsheet in one operation. It then uses Excel's StDev function to calculate the standard deviation of the data inserted into Excel.
ExcelGraph.vee | Uses Excel and ActiveX Automation to insert data into a spreadsheet. It then instructs Excel to create a new Chart and formats the Chart appropriately.
ExcelUFunction.vee | Uses Excel and ActiveX automation to insert random data into a spreadsheet one cell at a time. It then uses Excel's Average function to calculate the average of the data inserted into Excel.
ExcelWeather.vee | Uses Excel and ActiveX Automation to calculate the weather report.

Calling VEE from Excel

SpreadsheetApp.xls is an Excel file that calls VEE functions in lib.vee. One function synthesizes a pulse from data read from a file; the other function displays the pulse with test limits. To open an example, use the Windows Explorer and double-click this file:

<VEE_install_dir>\examples\CallableVEE\Excel\SpreadsheetApp.xls

See Also

Releasing ActiveX References


Microsoft Outlook
examples\ActiveXAutomation

The applications and related ActiveX automation type libraries referenced here must be installed on your system before the programs will run properly.

Microsoft Outlook Example
Example Names | Description
Outlook.vee | Sends e-mail using the ActiveX Automation capability of VEE and Microsoft Outlook.

See Also

Releasing ActiveX References


Microsoft Word
examples\ActiveXAutomation

The applications and related ActiveX automation type libraries referenced here must be installed on your system before the programs will run properly.

ActiveX Automation Examples
Example Name | Description
Word.vee | Uses Word and ActiveX Automation to insert test data and a bitmap of a VEE UserFunction into a Word document.
WordDataSheet.vee | Performs ActiveX Automation search and replace in a Word document used as a template for a single page datasheet.
WordMailMerge.vee | Uses ActiveX Automation to perform mail merge in a Word document named mmerge.doc, using the database file mmerger.mdb.

See Also

Releasing ActiveX References


Callable VEE

Old VEE RPC API
examples\CallableVEE\Rpc_api

Old VEE RPC Example
Example Name | Description
lib.vee | Is a VEE library which contains several callable functions, including the DS1 pulse test functions.

DS1 Pulse Test

CallVEE.c is a C source file that calls two VEE functions in lib.vee. One synthesizes a pulse from data read from a file. The other displays the pulse with test limits.

The preferred method of calling VEE 6.0 and above is the Callable VEE ActiveX Automation Server. However, the original C API still works. You might choose the old method if you are working in K&R C (rather than C++).

To open an example, use the Windows Explorer and double-click this file:

<VEE_install_dir>\examples\CallableVEE\Rpc_api\CallVEE.c


MultiTrace Examples

Multiple Traces Examples

Example Name

Description

2dXyTrace.vee

Demonstrates how to display multiple traces on Graphic Objects through one single input pin.

MatrixInputStripChart.vee

Randomly generate four Real64 data between -100 and 100 repeatedly, and then display them in a Strip Chart.


PP_Examples

Programmatic Properties Examples

Example Name

Description

ProgrammaticPropertyDemo.vee

Demonstrates how to GET/SET properties programmatically.

DemoTabIndexChangeDemo.vee

Demonstrates how to programmatically change TableIndex for objects in a panel view.

SelectionControlPropertiesDemo.vee

Demonstrates how to programmatically change EnableEditing, EnumIndex, EnumValue, EnumValues for Selection controls


Lib

VEE Lib Examples
examples\Lib

There is \lib directory in VEE's install directory. It contains various functions and objects that may be useful in your VEE programs. You can import these objects by using File [image] Merge. The following examples show these library objects being used in complete programs.

Lib Examples
Example Names | Description
1dto2d.vee | Illustrates use of the Formula object and Array building syntax to construct a 2D array from a larger 1D input array when the array sizes are fixed.
2dto1d.vee | Illustrates use of the MatToAry.vee library object for "flattening" multiple dimensioned arrays into a 1D array.
barcht1.vee | Illustrates use of the BarChart.vee library object to display an array of data.
barcht2.vee | Illustrates use of the BarPF.vee library object to display an array of data by comparing each element to a fixed limit.
barcht3.vee | Illustrates use of the BarStack.vee library object to display two arrays of data simultaneously
barcht4.vee | Illustrates use of the BarComp.vee library object to display two arrays of data simultaneously.
dialog.vee | Illustrates use of the dialog library object for requesting user input at a specific point in your program. This program is a starting point for more complicated dialog boxes; for simple dialog boxes, use the Dialog Box objects built into VEE on the Data menu.
keypad.vee | Illustrates the use of the keypad.vee library object.
maparray.vee | Illustrates use of the mapArray.vee library object to build an array of numbers corresponding to each element of a Spectrum or Waveform input.
multiplex.vee | Demonstrates use of a Formula object as a Multiplexer object.
pathsep.vee | Illustrates use of the pathSep.vee library object to normalize the path separator character for both DOS and posix path names.
piechart.vee | Illustrates use of the PieChart.vee library object to display an array of data.
rmfile.vee | Demonstrates the use of the rmfile.vee library object.
SMTPMail.vee | Is a library object that demonstrates the use of the To/From Socket object to implement send-only Simple Mail Transfer Protocol (SMTP) functionality.
xy_cntrl.vee | Shows how to adjust traces and scales on an XY Trace display, using the Record Constant objects Traces Control and Scales Control. These controls are in the XY_cntrl.vee library object. To control only one scale or trace, open the Properties dialog box for the Traces Control or Scales Control, then set Array Size to 0 on the General tab


Concepts

VEE Programming Concepts
examples\Concepts

VEE Programming Examples
Example Name | Description
AdvancedDialog.vee | Shows how to create a dialog box that takes initial parameters, validates user input, and returns the information the user entered.
alternateToIfThenElse.vee | Demonstrates the use of the demultiplexer object and the junction object. Shows how they can be used to eliminate complex if/then structures.
ascii.vee | Illustrates how to convert a keyboard character to its ASCII code, and how to convert an ASCII code to a character.
convert.vee | Shows how easily VEE handles different types of data including DECIMAL, HEXADECIMAL, OCTAL, and BINARY.
complex.vee | Illustrates generating, adding, processing, and displaying Complex and Polar Complex numbers.
datacomp.vee | Compresses new data by checking for a change and recording only the changes with a time stamp.
feedback.vee | Illustrates feedback and how it can be used to implement a simple one-pole IIR digital filter.
fib.vee | Illustrates using feedback to model an equation such as the Fibonacci sequence: a(n) = a(n-1) + a(n-2).
holdBackAndDelay.vee | Shows the use of the Gate and Delay objects to control program flow.
if.vee | Illustrates the use of the If/Then/Else object to output a value.
ifThenExpressions.vee | Illustrates the use of triadic expressions.
infoAbout.vee | Describes the pop-up help device used in many of these program examples.
integrate.vee | Shows how to integrate functions with upper and lower bounds that are entered into a dialog box, then graphically display the integration results.
iterateColumnOrRow.vee | Iterates a one dimensional array. Shows how to iterate either rows or columns.
iterateOneDim.vee | Iterates a one dimensional array using the For Each object.
iterateRecordFields.vee | This example illustrates how to iterate through the fields in a record scalar. Notably, the For Each object is used in this example.
iterateTwoDim.vee | Iterates a two dimensional array using the For Each object.
layout1.vee | Demonstrates how laying out a VEE program using left to right data flow helps the programs readability.
layout2.vee | Demonstrates the effect of aligning and sizing objects on a programs layout.
loop.vee | Generates a series of random integers, each between 1 and 10, and finds out how many of them sum up to be less than or equal to 100.
magphase.vee | Illustrates a simple method of displaying the Magnitude and Phase vs. Frequency from a time-domain waveform. Note that the Mag/Phase Display in the program is a UserObject and not a supplied display object.
nestedRecord.vee | Demonstrates the nesting ability of the Build Record object.
oneshot.vee | Illustrates the use of a Toggle Button to create a One-Shot Button.
opt1.vee | Uses Parallel Math to operate on arrays of data.
opt2.vee | Reads a two-dimensional array of data from a file.
opt3.vee | Compares how Formula objects in two threads evaluate expressions allowing Sieve to run faster or slower.
redim.vee | Shows how to change the dimensions of an array.
scattrgm.vee | Illustrates a method of plotting scattergrams using the X vs Y display.
strings.vee | Demonstrates use of the built-in String functions available in the Function & Object Browser (on the Device [image] Function & Object Browser menu).
subrecord.vee | Shows how sub-records can be treated as records also.
text1.vee | Illustrates several ways to combine text strings.
timetick.vee | Uses the On Cycle object (on Flow [image] Repeat menu) to generate a 1-second Time-Of-Day clock.
tofrom1.vee | Illustrates how to save data between successive executions of a program by writing the latest data to a file after reading and modifying data previously written to the same file.
tofrom2.vee | Illustrates how one thread writes to a file and a second thread reads the data and processes it at its own speed.
tofrom3.vee | Shows how to use the Selection Control objects such as Radio Buttons (on the Data [image] Selection Control menu), and the WRITE CASE I/O transaction together. Use this technique to map easily-understood strings into corresponding output strings.
tofrom4.vee | Illustrates how to use transaction I/O to write VEE waveforms. This program combines some of the concepts of data type conversion and transaction I/O. The To String object is used for convenience in viewing results. You may substitute a To File object with the same transactions for any To String.
tr_ctrl.vee | Shows how to use the Traces control input pin to a Strip Chart display. The control pin changes the line color from green to red, depending on the value of the data.
truefals.vee | Shows three ways to generate TRUE and FALSE text strings from a number.
UserFunctions.vee | Demonstrates how UserFunctions are called, and how they can be used throughout a program without modification.
whichos.vee | Demonstrates how to read the computers operating system and platform using the whichOS() and whichPlatform() functions.
wizbang.vee | Demonstrates the use of Alarms, Indicators, and Controls.
zerofill.vee | Illustrates several methods of extending an array by zero filling to a prescribed length. Use of math functions within the Formula object is illustrated, as is use of Allocate Array and ramp to generate fixed arrays.


Visual Basic
examples\CallableVEE\VisualBasic

DS1 Pulse Test

CallVEE.vbp is a Visual Basic project. The program calls two VEE functions in lib.vee. One synthesizes a pulse from data read from a file. The other displays the pulse with test limits. If Microsoft Visual Basic is installed on your system, you can open an example by double-clicking this file in the Windows Explorer.

<VEE_install_dir>\examples\CallableVEE\VisualBasic\CallVEE.vbp


Visual Basic Script

VB Script
examples\CallableVEE\VBScript

If Microsoft VB Script is available on your system, you can run these examples by double-clicking them in the Windows Explorer.

DS1 Pulse Test

CallVEE.vbs is a VB Script file that calls two VEE functions in lib.vee. One synthesizes a pulse from data read from a file. The other displays the pulse with test limits.

<VEE_install_dir>\examples\CallableVEE\VBScript\CallVEE.vbs

Getting Callable VEE Server Information

GetServerInfo.vbs is a VB Script file that returns information about the registered Callable VEE Server, for example, the I/O configuration file being used by the host.

<VEE_install_dir>\examples\CallableVEE\VBScript\GetServerInfo.vbs

Create and Display a Waveform

GetWaveform.vbs is a VB Script file that uses one of VEE's unique data types. It shows how to create, pass, and return Waveform data.

<VEE_install_dir>\examples\CallableVEE\VBScript\GetWaveform.vbs

Finding and Loading a VEE Library

UsingInstallDir.vbs is a VB Script file that discovers VEE's install directory, then loads and calls a VEE library relative to that directory.

<VEE_install_dir>\examples\CallableVEE\VBScript\UsingInstallDir.vbs


Visual C++
examples\CallableVEE\VisualC++

DS1 Pulse Test

CallVEE.cpp is a Visual C++ file that calls two VEE functions in lib.vee. One synthesizes a pulse from data read from a file. The other displays the pulse with test limits. If Microsoft Visual C++ is installed on your system, you can open an example by double-clicking this file in the Windows Explorer.

<VEE_install_dir>\examples\CallableVEE\VisualC++\CallVEE.cpp


ASCII Table

The following table lists the ASCII 7-bit character codes:

 | Binary | Octal | Hex | Decimal | GPIB Message
NUL | 0000000 | 000 | 00 | 0 |
SOH | 0000001 | 001 | 01 | 1 | GTL
STX | 0000010 | 002 | 02 | 2 |
ETX | 0000011 | 003 | 03 | 3 |
EOT | 0000100 | 004 | O4 | 4 | SDC
ENQ | 0000101 | 005 | 05 | 5 | PPC
ACK | 0000110 | 006 | 06 | 6 |
BEL | 0000111 | 007 | 07 | 7 |
BS | 0001000 | 010 | 08 | 8 | GET
HT | 0001001 | 011 | 09 | 9 | TCT
LF | 0001010 | 012 | 0A | 10 |
VT | 0001011 | 013 | 0B | 11 |
FF | 0001100 | 014 | 0C | 12 |
CR | 0001101 | 015 | 0D | 13 |
SO | 0001110 | 016 | 0E | 14 |
SI | 0001111 | 017 | OF | 15 |
DLE | 0010000 | 020 | 10 | 16 |
DC1 | 0010001 | 021 | 11 | 17 | LLO
DC2 | 0010010 | 022 | 12 | 18 |
DC3 | 0010011 | 023 | 13 | 19 |
DC4 | 0010100 | 024 | 14 | 20 | DCL
NAK | 0010101 | 025 | 15 | 21 | PPU
SYN | 0010110 | 026 | 16 | 22 |
ETB | 0010111 | 027 | 17 | 23 |
CAN | 0011000 | 030 | 18 | 24 | SPE
EM | 0011001 | 031 | 19 | 25 | SPD
SUB | 0011010 | 032 | 1A | 26 |
ESC | 0011011 | 033 | 1B | 27 |
FS | 0011100 | 034 | 1C | 28 |
GS | 0011101 | 035 | 1D | 29 |
RS | 0011110 | 036 | 1E | 30 |
US | 0011111 | 037 | 1F | 31 |
SPACE | 0100000 | 040 | 20 | 32 | listen 0
! | 0100001 | 041 | 21 | 33 | listen 1
" | 0100010 | 042 | 22 | 34 | listen 2
# | 0100011 | 043 | 23 | 35 | listen 3
$ | 0100100 | 044 | 24 | 36 | listen 4
% | 0100101 | 045 | 25 | 37 | listen 5
& | 0100110 | 046 | 26 | 38 | listen 6
' | 0100111 | 047 | 27 | 39 | listen 7
( | 0101000 | 050 | 28 | 40 | listen 8
) | 0101001 | 051 | 29 | 41 | listen 9
* | 0101010 | 052 | 2A | 42 | listen 10
+ | 0101011 | 053 | 2B | 43 | listen 11
, | 0101100 | 054 | 2C | 44 | listen 12
- | 0101101 | 055 | 2D | 45 | listen 13
. | 0101110 | 056 | 2E | 46 | listen 14
/ | 0101111 | 057 | 2F | 47 | listen 15
0 | 0110000 | 060 | 30 | 48 | listen 16
1 | 0110001 | 061 | 31 | 49 | listen 17
2 | 0110010 | 062 | 32 | 50 | listen 18
3 | 0110011 | 063 | 33 | 51 | listen 19
4 | 0110100 | 064 | 34 | 52 | listen 20
5 | 0110101 | 065 | 35 | 53 | listen 21
6 | 0110110 | 066 | 36 | 54 | listen 22
7 | 0110111 | 067 | 37 | 55 | listen 23
8 | 0111000 | 070 | 38 | 56 | listen 24
9 | 0111001 | 071 | 39 | 57 | listen 25
: | 0111010 | 072 | 3A | 58 | listen 26
; | 0111011 | 073 | 3B | 59 | listen 27
< | 0111100 | 074 | 3C | 60 | listen 28
= | 0111101 | 075 | 3D | 61 | listen 29
> | 0111110 | 076 | 3E | 62 | listen 30
? | 0111111 | 077 | 3F | 63 | UNL
@ | 1000000 | 100 | 40 | 64 | talk 0
A | 1000001 | 101 | 41 | 65 | talk 1
B | 1000010 | 102 | 42 | 66 | talk 2
C | 1000011 | 103 | 43 | 67 | talk 3
D | 1000100 | 104 | 44 | 68 | talk 4
E | 1000101 | 105 | 45 | 69 | talk 5
F | 1000110 | 106 | 46 | 70 | talk 6
G | 1000111 | 107 | 47 | 71 | talk 7
H | 1001000 | 110 | 48 | 72 | talk 8
I | 1001001 | 111 | 49 | 73 | talk 9
J | 1001010 | 112 | 4A | 74 | talk 10
K | 1001011 | 113 | 4B | 75 | talk 11
L | 1001100 | 114 | 4C | 76 | talk 12
M | 1001101 | 115 | 4D | 77 | talk 13
N | 1001110 | 116 | 4E | 78 | talk 14
O | 1001111 | 117 | 4F | 79 | talk 15
P | 1010000 | 120 | 50 | 80 | talk 16
Q | 1010001 | 121 | 51 | 81 | talk 17
R | 1010010 | 122 | 52 | 82 | talk 18
S | 1010011 | 123 | 53 | 83 | talk 19
T | 1010100 | 124 | 54 | 84 | talk 20
U | 1010101 | 125 | 55 | 85 | talk 21
V | 1010110 | 126 | 56 | 86 | talk 22
W | 1010111 | 127 | 57 | 87 | talk 23
X | 1011000 | 130 | 58 | 88 | talk 24
Y | 1011001 | 131 | 59 | 89 | talk 25
Z | 1011010 | 132 | 5A | 90 | talk 26
[ | 1011011 | 133 | 5B | 91 | talk 27
\ | 1011100 | 134 | 5C | 92 | talk 28
] | 1011101 | 135 | 5D | 93 | talk 29
^ | 1011110 | 136 | 5E | 94 | talk 30
_ | 1011111 | 137 | 5F | 95 | UNT
` | 1100000 | 140 | 60 | 96 | second 0
a | 1100001 | 141 | 61 | 97 | second 1
b | 1100010 | 142 | 62 | 98 | second 2
c | 1100011 | 143 | 63 | 99 | second 3
d | 1100100 | 144 | 64 | 100 | second 4
e | 1100101 | 145 | 65 | 101 | second 5
f | 1100110 | 146 | 66 | 102 | second 6
g | 1100111 | 147 | 67 | 103 | second 7
h | 1101000 | 150 | 68 | 104 | second 8
i | 1101001 | 151 | 69 | 105 | second 9
j | 1101010 | 152 | 6A | 106 | second 10
k | 1101011 | 153 | 6B | 107 | second 11
l | 1101100 | 154 | 6C | 108 | second 12
m | 1101101 | 155 | 6D | 109 | second 13
n | 1101110 | 156 | 6E | 110 | second 14
o | 1101111 | 157 | 6F | 111 | second 15
p | 1110000 | 160 | 70 | 112 | second 16
q | 1110001 | 161 | 71 | 113 | second 17
r | 1110010 | 162 | 72 | 114 | second 18
s | 1110011 | 163 | 73 | 115 | second 19
t | 1110100 | 164 | 74 | 116 | second 20
u | 1110101 | 165 | 75 | 117 | second 21
v | 1110110 | 166 | 76 | 118 | second 22
w | 1110111 | 167 | 77 | 119 | second 23
x | 1111000 | 170 | 78 | 120 | second 24
y | 1111001 | 171 | 79 | 121 | second 25
z | 1111010 | 172 | 7A | 122 | second 26
{ | 1111011 | 173 | 7B | 123 | second 27
| | 1111100 | 174 | 7C | 124 | second 28
} | 1111101 | 175 | 7D | 125 | second 29
~ | 1111110 | 176 | 7E | 126 | second 30
[del] | 1111111 | 177 | 7F | 127 |


Error Codes

Use the following table to find the error message that corresponds to the error code output from an error terminal.

Error Code | Description
Objects |
300 | The input terminal number <n> is not connected
301 | Input <n> is not present (valid range = [<n>..<n>])
302 | No additional inputs are allowed -- limited to <n>
303 | The input must be <type>
304 | The input cannot be <type>
305 | Input(s) mismatch: <name>, <name>
306 | Required input <name> is not present
308 | Required output <name> is not present
309 | Output(s) mismatch: <name>, <name>
310 | Output <n> is not present (valid range = [<n>..<n>])
311 | No additional outputs are allowed -- limited to <n>
312 | No <type> was selected
313 | <operation> is not supported
314 | Invalid combination of parameters: <n>
315 | Component <name> cannot be added
317 | There is no panel to switch to
318 | UserFunction <name> has no panel view
320 | Child process failed to run
321 | Child process died
322 | Could not open the pipe
323 | List has no elements
330 | The Max value must be greater than the Min value
331 | VEE cannot load or execute this program
340 | Cannot compile an object with more than one xeq pin
341 | The xeq pin must be the bottom-most data in pin
342 | Cannot compile a context object with an xeq pin
343 | UserObject cannot reside in its Edit Window
344 | CallBox cannot reside in calling function (recursion is not allowed)
345 | Duplicate device name. Change <name> to be unique.
346 | Must specify a Name for the device.
347 | Cannot compile a program with error pins on iterators or junctions
Containers |
400 | Value is empty or nil (could be zero-element array)
401 | Value out of bounds (valid range = [<n>..<n>])
402 | <name> value must be <type>
403 | <name> value is out of range
404 | Numeric value must be positive
405 | <name> was not found
410 | Value must be a scalar
411 | Value must be an array
412 | Value must be a scalar or linear array
413 | Value must be a <n> dimensional array
414 | Value must be a waveform or linear array
415 | Values must have same number of dimensions
416 | Values must have same size and shape
417 | Record structures must match
418 | Records cannot be merged
420 | Value must be a square matrix
421 | Shapes of matrix values are inappropriate for matrix multiply
422 | Value must be a matrix with an ODD number of columns
430 | Scalar cannot be accessed by a non-zero index
431 | Value for an array index is out of range
432 | Values for array/sub-array indices are inappropriate
433 | Too many array dimensions given (maximum = <n>)
434 | Value must have <n> field(s)
435 | Both values must have the same number of fields
440 | Invalid operation for data type <type>
441 | Invalid operation for scalar value
442 | Invalid operation for a <n> dimensional array
443 | Operation valid only for numeric values
444 | Invalid assignment of Declared Variable
445 | Attempted access to Declared Variable <name> which has not yet been initialized
450 | Operation requires that array be mapped
451 | Array mappings for values must match
452 | Sample frequency for array mappings must match
453 | <type> cannot have vertical steps
454 | Construction of an array is not allowed
460 | Cannot increment/decrement arrays and functions
461 | Value is > 16 digits -- cannot increment/decrement
462 | Attempt to overwrite constant or parameter <name> failed
463 | Input coordinates are not monotonic over "X"
464 | Unable to convert <type> to <type>
465 | <action> is not allowed <message>
MATH |
500 | Illegal values for argument(s) in function <name>
501 | Function <name> does not allow negative values
502 | Function <name> requires <n> argument
510 | Math error in function <name>
511 | Division/Modulo by zero
512 | Negative value cannot be raised to a non-integer power (<n>)
513 | Zero cannot be raised to a non-positive power (<n>)
514 | Numeric data overflow in function <name>
515 | Numeric data underflow in function <name>
516 | Overflow of sum occurred during calculation of <name>
517 | Function or UserFunction: '<name>' is unknown
520 | Bounds for LOG mapping must be > 0
521 | X-data for LOG mapped function must be > 0
522 | Derivatives of order <n> are not supported
523 | Interpolation on multi-dimensional arrays is not supported
ActiveX |
550 | ActiveX object <name> failed
551 | An ActiveX object returned incompatible data type <name>
552 | <name> in the referenced ActiveX object failed
553 | An ActiveX object returned an error during <action> <name>
554 | <name> is not a member of the referenced ActiveX object
555 | Attempt to Set property <name> without specifying a value
556 | ActiveX object does not implement the interface <name>
557 | ActiveX object could not be created
558 | The target operating system platform for <name> is not WIN32
559 | Could not load type library from <name>
560 | The Property <name> was not found
561 | There isn't any type information loaded for <name>
562 | Invalid CLSID: <number>
563 | Invalid ProgID: <name>
564 | Could not establish event connection to <name>
565 | Cannot access ActiveX Object <name>
566 | An ActiveX object returned an incompatible value
567 | Could not get instance of ActiveX object <name>
568 | Programmatic access to VEE object property failed
569 | ActiveX Automation array error
570 | Cannot access data in ActiveX Automation array
571 | Cannot create remote objects. DCOM is not installed. Download and install DCOM95 from the Microsoft web site
MATLAB SCRIPT |
590 | MATLAB not installed. Reinstall VEE and select the MATLAB Script install option.
591 | Could not start the MATLAB Script engine
592 | Generic MATLAB error <message>
593 | Error in MATLAB Script
594 | MATLAB data contains infinity or NaN
EXPRESSIONS |
600 | Syntax error: <description>
601 | Invalid expression: <description>
602 | Function was not found: <name>
603 | Variable was not found: <name>
604 | Function was not loadable: <name>
610 | Too many arguments supplied (maximum=<n>)
611 | Wrong number of parameters supplied to function <name>
620 | Name or string constant is too long (> n chars)
621 | Duplicate symbol name <name>
622 | Invalid variable/terminal name <name>
623 | Closing quote for the string was not found
624 | Illegal character(s) found while parsing string
625 | Illegal escape sequence <sequence>
626 | Duplicate record field name <name>
627 | Duplicate library name <name>
628 | Invalid record field name <name>
629 | Invalid UserFunction name <name>
630 | Invalid value
631 | Value of the expression must be either all zero or all non-zero
640 | Mismatch error: Expected <name>, got <name>
641 | Unknown parameter: <name>
642 | Undefined parameter: <name>
643 | This program has no execution window
650 | Library: <name> contains running functions. Cannot delete
660 | Invalid name: <name>
FILES |
700 | File <name> was not found
701 | End of file or no data found
702 | Cannot open file <name>: Permission denied
703 | Cannot read file <name>
704 | Cannot write to file <name>
705 | Read error on file <name>
706 | End of file or no match found
707 | Needed to read <n>, found only <m>
708 | Bytes read must be multiple of data size
710 | File <name> is not a named pipe
711 | Cannot create file <name>
712 | File <name> already exists
713 | Invalid directory name <name> in path
714 | File is a directory
715 | Directory is not empty
716 | Cannot execute file <name>
717 | Invalid working directory <name>
718 | Could not create process. (Windows error number: <n>)
720 | File is in use
721 | Device is Busy
722 | Cannot access a different file system
723 | Too many files are open
724 | File is too large
725 | Disk is full
726 | Error during 'seek' of file
727 | Bad system file number
728 | Too many symbolic links
729 | File format is invalid
730 | No UserFunctions found in file
733 | Cannot merge secured program
734 | Could not create a shared memory segment
736 | Cannot read binary file <name>
737 | Cannot write to binary file <name>
738 | Could not recover from parsing error
739 | Stack pointer corrupted after return from compiled function
.NET |
751 | .NET invocation failure
752 | Exception
753 | No default member
754 | Cannot access .NET
755 | No property put value
756 | Object could not be created
757 | Could not get member information
758 | Could not get VEE to .NET
759 | Could not get Namespace
760 | Type not found
761 | Event connect failed
763 | Could not establish event connection
764 | Failed to build .NET operation
765 | The control may have to added to another control programmatically
I/O |

800

No such device or incorrect address

801

Configuration error: <description>

802

Incorrect special device file <name> found

803

Device, <name>, is not message based

804

Invalid access to memory on device, <name>

810

Instrument driver error <n>: <description>
Refer to your instrument manual for further information

811

I/O error or timeout occurred

812

Invalid bin block header

813

Must be the active system controller to access GPIB

814

Lock acquisition failed on <device> <interface>

815

Error returned from VXIplug&play function call, error value <n>

816

Error returned from VXIplug&play init() function call, error value <n>

817

Error returned from NIDAQ driver function call

818

Error returned from NIDAQ NIxxxx_init() function call

821

Transaction not supported for <name> interface

830

Could not initiate DDE link to application <name>, topic <name>

831

DDE POKE to item <name> failed

832

DDE REQUEST from item <name> failed

833

DDE EXECUTE failed

850

Host, <name>, is unknown

851

There is no Service Manager on host, <name>

852

Networking is not initialized on this host

853

Connection has timed out

854

An interrupt occurred before receive on network

855

The connection has been shut down by the peer

856

The operating system is out off buffer space

857

The network is down

858

An interrupt occurred before the connection to the host <name>

859

The port, <name>, is already in use

860

Attempted connection to <name> has timed out

861

Service Manager on <name> has not responded

862

Service, <name>, on host, <name>, has not responded

863

Service, <name>, not found on host, <name>

864

Service, <name>, on host, <name>, cannot be started

865

Error in service, <name>, on host, <name>

866

The connection was refused on host, <name>

867

The UserFunction, <name>, in service, <name>, was not found

868

Permission denied for user, <name>, on host, <name>

869

Remote Service, <name>, on host, <name>, reports error: <n>

870

Non-blocking receive

871

Remote debug terminated before completion

876

Failure code returned in COM HRESULT

877

Expected parameter <name> to be passed ByRef

878

Invalid value returned from <name>

879

The VEE data container is empty

880

The size of array: <name> must be a multiple of: field count <n>

SYSTEM

900

Operation is not allowed while the program is running

901

Illegal form of feedback

902

Unexpected BREAK encountered

903

Unexpected CONTINUE encountered

904

Invalid device encountered

905

Incorrect revision "<rev>" (Expected "<rev>")

906

A Thread with feedback requires a START object

910

Process is out of memory, save your program IMMEDIATELY

911

Floating-point exception, possible overflow/underflow

912

There are too many system processes

913

Reset or Break encountered

914

Cannot open display

915

The operating system is out of resources

920

Write on a pipe with no process to read it (signal = <n>)

921

User-defined signal 1 received (signal = <n>)

922

User-defined signal 2 received (signal = <n>)

930

Error(s) encountered during PreRun

935

A Junction is required inside of feedback cycles

936

UserFunction is not re-entrant

937

Sample & Hold was not given any data

938

VEE was unable to compile this part of the program

939

Cannot push START when thread is connected to input terminals

940

Illegal form of feedback

941

T1 must be activated before T2

950 through 999

EXCEL LIBRARY

2001

  • An attempt to navigate past the 256th column or before the 1st column;

  • An attempt to navigate above the first row or below the last row;

  • Invalid cell or range address found will attempting to convert to numeric Row and
    column: <column>;

  • An attempt to send data past the 256th column.

2002

  • An attempt to send data with more than three dimensions;

  • An error with data type \nENUM - can only be sent as part of a record\nSPECTRUM - see examples\nCCOMPLEX, see examples\nPCCOMPLEX, see examples\nCOORD, see examples\nOBJECT - not supported by Excel Library;

  • An attempt to send a three dimensional or higher record

2003

This Sheet is protected and cannot be changed

2004

  • This Sheet cannot be found in the current Workbook;

  • This Workbook cannot be found in the currently open set of Workbooks

2005

An attempt to send data with no Workbook open

2006

SendRecord input is not a record

2007

  • Unrecognized value for SendDataSettings.ThreeDArrays;

  • Unrecognized input terminal value for Print

2008

Size of array > 254. Cannot create more than 254 new Sheets

2022

Unrecognized Chart type

2023

Error with line chart settings Names array. Probable cause is that the array is not as large as the data array. Also verify, if you select Logarithmic, that there are no negative values in the data.

2025

Error on ActiveChart.ApplyCustomType(xlBuiltIn, “Logarithmic”).  Non-English versions of Office do not support this.  See online Help for workarounds.

See Also

About .NET Errors in VEE


Activate

1. To send a container to a terminal. See also Container and Terminal.

2. The action that resets the context of a UserObject before it operates each time. See also Context and PreRun.


ActiveX

A communication mechanism that allows processes to communicate on the Windows platform. ActiveX is family of technologies, based on Microsoft COM, that includes various aids to distributed computing, such as ActiveX Controls and ActiveX Automation Servers.


Allocate

To initialize a VEE array. Allocation sets the number of dimensions, the number of elements in each dimension, and fills the array with initial data. For example, a two-dimensional integer array is filled with 0 values by default.


Array

A data shape corresponding to a mathematical array, which contains a grouping of data items (all of the same data type) in one or more dimensions. The data items are accessed by means of array indexes. In VEE, a one-dimension array is called Array 1D, a two-dimension array is Array 2D, and so forth. See also Data Shape.


Asynchronous

In asynchronous operation, a device operates without a common signal to synchronize events -- the events occur at unspecified times. VEE control pins (for example, the Clear pin on a display object) are asynchronous.


Auto Execute

An option on the object menus of the data constant objects. If Auto Execute is set, and if the program is not already running, the object operates when its value is edited. Auto Execute is ignored while the program is running.


Bitmap

A bit pattern or picture. In VEE you can display a bitmap with a Picture object or on any icon. You can also display a bitmap on the background of a main program panel view, a UserObject panel view, or a UserFunction panel view.


Breakpoint

A tool for debugging a program. If you set a breakpoint for an object, the program will pause just before that object executes.


Buffer

An area in memory where information is stored temporarily.


Button

A graphical object in VEE that simulates a momentary switch or selection button, and which appears to pop out from your screen. When you "press" a button in VEE, by clicking on it with the mouse, an action occurs. (May also refer to the left or right mouse button.)


Cascading Menu

A sub-menu on a pull-down or pop-up menu that provides additional selections.


Checkbox

A recessed square box on menus and dialog boxes that allows you to select a setting. To select a setting, click on the box so a check mark appears in the box to indicate a selection has been made. To cancel the setting, simply click on the box again.


Click

To press and release a mouse button. Clicking usually selects a menu feature or object in the VEE window. See also Double-Click and Drag.


Clone

A menu item on object menus that duplicates objects and their interconnections, placing a copy of them in the Paste buffer. Clone copies all the attributes of the cloned objects including pins, parameters, and size.


Compiled Function

A user-defined function created by dynamically linking a program, written in a programming language such as C, into the VEE process. The user must create a DLL (Dynamically Linked Library) file and a definition file. The Import Library object attaches the DLL to the VEE process and parses the definition file declarations. The Compiled Function can then be called with the Call Function object, or from certain expressions. See also UserFunction and Remote Function.


Component

A single instrument function or measurement value in a VEE instrument panel or component driver. For example, a voltmeter driver contains components that record the range, trigger source, and latest reading. See also Component Driver, Driver Files, State, and Instrument Panel.


Component Driver

An instrument control object that reads and writes values to components you specifically select. Use component drivers to control an instrument using a driver by setting the values of only a few components at a time. (Component drivers do not support coupling.)


Composite Data Type

A data type that has an associated shape. See also Data Shape and Data Type.


Container

See Data Container.


Context

A level of the work area that can contain other levels of work areas (such as nested UserObjects), but is independent of them.


Control Pin

An asynchronous input pin that transmits data to the object without waiting for the object's other input pins to contain data. For example, control pins in VEE are commonly used to clear or autoscale a display.


Coupling

The inter-relationship of certain functions in an instrument. If, in an instrument panel, functions A and B are coupled, changing the value of A may automatically change the value of B, even though you do not change B explicitly.


Cursor

A pointer (caret) in an entry field that shows where alphanumeric data will appear when you type information from the keyboard.


Cut Buffer

The buffer that holds objects that you cut or copy. You can then paste the object back into the work area with Edit [image] Paste


Data Container

The data package that is transmitted over lines and is processed by objects. Each data container contains data and the data type, data shape, and mappings (if any).


Data Field

The field within a transaction specification in which you specify either the expression to be written (WRITE transactions), or the variable to receive data that is read (READ transactions). See also Transaction.


Data Flow

The flow of data through and between VEE objects. Data flows from left to right through objects, but an object does not execute until it has data on all of its data input pins. Data is propagated from the data output pin of one object to the data input pin of the next object. Data flow is the chief factor that determines the execution of a VEE program.


Data Input Pin

A connection point on the left side of an object that permits data to flow into the object.


Data Output Pin

A connection point on the right side of an object that propagates data flow to the next object and passes the results of the first object's operation on to the next object.


DataSet

A collection of "Record" containers saved into a file for later retrieval. The To DataSet object collects Record data on its input and writes that data to a named file (the DataSet). The From DataSet object retrieves Record data from the named file (the DataSet) and outputs that data as Record containers on its Rec output pin. See also Record.


Data Shape

Each data container has both a shape and type. The data shape can be either a scalar or an array. The data shape can be either a scalar or an array of one or more dimensions. In VEE, a one-dimension array is called Array 1D, a two-dimension array is Array 2D, and so forth.


Data Type

Each data container has both a type and shape. VEE supports several data types including Text, Int16, Real64, Complex, Waveform, etc.


DDE (Dynamic Data Exchange)

A communication mechanism that allows processes to communicate on the Windows platform. DDE is an older mechanism that was superceded by ActiveX .


Default

A value or action that is selected automatically. For example, VEE uses certain default colors and fonts, which you can change using the Default Preferences dialog box.


Default Button

The button in a dialog box that is activated by default if Enter or Return is pressed, or the selection is double-clicked. The label of the default button is in bold text.


Demote

To convert from a data type that contains more information to one that contains less information. See also Data Type and Promote.


Detail View

The view of a VEE program that shows all the objects and the lines between them.


Device Driver

See Interface Driver.


Dialog Box

A secondary window displayed when VEE requires information from you before it can continue. For example, a dialog box may contain a list of files from which you may choose.


Direct I/O Object

An instrument control object that allows VEE to directly control an instrument without using a dedicated driver.


DLL (Dynamically Linked Library)

A collection of functions written in C that can be called from VEE for Windows. DLLs can be created by experienced C programmers using tools available from Microsoft.


Double-Click

To press and release a mouse button twice in rapid succession. Double-clicking is usually a short-cut to selecting and performing an action. For example, double-clicking on a file name from File [image] Open will select the file and open it.


Drag

To press and continue to hold down a mouse button while moving the mouse. Dragging moves something (for example, an object or scroll bar).


Driver

Software that allows a computer to communicate with other software or hardware. See also Component Driver, Driver Files, Interface Driver, and Instrument Panel.


Driver Files

A set of files included with VEE that contains the information needed to create instrument panel and component driver objects for instrument control.


Drop-Down List

A list of selections obtained by clicking on the arrow to the right of a selection field.


Entry Field

A field that is typically part of a dialog box or an editable object, which is used for data entry. An entry field is editable when its background is white.


Error Message

Information that appears in an error dialog box, explaining that a problem has occurred.


Error Pin

A pin that traps any errors that occur in an object. Instead of getting an error message, the error number is output on the error pin. When an error is generated, the data output pins are not activated.


Execute

The action of a program (or its parts) running.


Execution Flow

The order in which objects operate. See also Data Flow.


Expression

An equation in an entry field that may contain input terminal names, local or global variable names, math operators, built-in functions, and user-defined functions. An expression is evaluated at run time. Expressions are allowed in Formula, If/Then/Else, Get Values, Get Field, Set Field, Sequencer, and Dialog Box objects, and in I/O transaction objects.


Feedback

A continuous thread path of sequence and/or data lines that uses values from the previous execution to change values in the current execution.


Flow

See Data Flow and Execution Flow.


Font

The size and style of a typeface.


Function

The name and action of objects where the output is a function of the input. These objects are located in the Function & Object Browser (Device [image] Function & Object Browser) and may be used in the Formula object. For example sqrt(x) is a function; + is not.


Global Variable

A named variable that is set globally, and which can be used by name in any context of a VEE program. For example, a global variable can be set with Set Variable in the root context of the program, and can be accessed by name with Get Variable or from certain expressions within the context of a UserObject. However, a local variable with the same name as the global variable takes precedence in an expression. See Variable.


Grayed Feature

A menu feature that is displayed in gray rather than black, indicating that the feature is not active or not available. Dialog box items such as buttons, checkboxes, or radio buttons may also be grayed.


Highlight

1. The colored band or shadow around an object that provides a visual cue to the status of the object.

2. The change of color on a menu feature that indicates you are pointing to that feature.


Host

1. To begin a thread or subthread. For example, the subthread that is hosted by For Count is the subthread that iterates.

2. In a distributed system, the computer running (or serving) a facility or an application.


Hypertext

A system of linking topics so that you can jump to a related topic when you want more information. In online help systems, typically hypertext links are designated with underlined text. When you click on such text, related information is presented.


Icon

1. A small, graphical representation of a VEE object, such as the representation of an instrument, a control, or a display.

2. A small, graphical representation of an application, file, or folder.


Instrument

An electronic device used for measurement and/or test stimulus. Instruments are connected to a computer with a GPIB, RS-232, GPIO, VXI, LAN, or USB interface. Specific VEE objects, such as the Direct I/O object and Panel Drivers, communicate with instruments.


Instrument Driver

See Driver Files, Component Driver, and Instrument Panel.


Instrument Panel

An instrument control object that forces all the function settings in the corresponding physical instrument to match the settings in the control panel displayed in the open view of the object.


Interface

A shared boundary between objects in different hardware (or software ) systems. GPIB, RS-232, GPIO, LAN, USB, and VXI are referred to as interfaces used for instrument I/O. Specific VEE objects, such as the Interface Event object, can only send commands to an interface.


Interface Driver

Software that allows a computer to communicate with a hardware interface, such as GPIB or RS-232.


Iterate

To repeat (loop) part of a VEE program using one of the Repeat objects (for example, For Count).


Library

A collection of often-used objects or programs grouped together for easy access.


Line

A link between two objects in VEE that transmits data containers to be processed. See also Thread.


Logical Unit

A number used to identify the logical address of a hardware interface. For example, the factory default logical unit for most GPIB interfaces is 7.


Loop

To repeat part of a VEE program using one of the Repeat objects (for example, For Count).


Main Menu

The menus located in the VEE menu bar. To open a main menu, click on the appropriate menu title in the menu bar. You can also use accelerators. For example, use Alt+F to open the File menu.


Main Work Area

Also known as the Main Window.


Main Window

The root, or primary, work area in which you develop a VEE program. This Main Window work area, resides in the work space of the VEE window, and is the parent context of all other contexts.


Mapping

A set of continuous or discrete values that express the independent variables for an array (for example, the time span of a waveform).


Maximize

To enlarge a window such as Main, UserObject, or UserFunction to fill all of the available work space in the VEE window using a maximize button. For the VEE window, this fills all of the available screen space.


Maximize Button

A button on a UserObject, UserFunction, and the Main window, that enlarges the window to fill all of the available work space in the VEE window. For the VEE window, this enlarges the window to fill all of the available screen space.


Menu

A collection of features that are presented in a list. See also Cascading Menu, Main Menu, Object Menu, Pop-Up Menu, and Pull-Down Menu.


Menu Bar

The bar at the top of the VEE window that displays the titles of the pull-down, main menus, from which you select features.


Menu Title

The name of a menu within the VEE menu bar. For example, File or Edit.


Minimize

1. To reduce an open view of an object to its smallest size -- an icon.

2. To reduce a window to its smallest size -- an icon.


Minimize Button

A button on an object, or the VEE window, that iconifies the object, or the VEE window.


Mouse

A pointing device that you move across a surface to move a pointer within the VEE window.


Mouse Button

One of the buttons on a mouse that you can click or double-click to perform a particular action with the corresponding pointer in the VEE window.


Network

A group of computers and peripherals linked together to allow the sharing of data and work loads.


Object

A graphical representation of an element in a program, such as an instrument, control, display, or mathematical operator. An object is placed in the work area and connected to other objects to create a program.


Object Menu

The menu associated with an object that contains features that operate on the object (for example, moving, sizing, copying, and deleting the object). To obtain the object menu, click on the object menu button at the upper-left corner of the object, or click the right mouse button with the pointer over the object.


Object Menu Button

The button at the upper-left corner of an open view object, which displays the object menu when you click on it.


Open

To start an action or begin working with a text, data, or graphics file. When you select Open from VEE, a program is loaded into the work area.


Open View

The representation of a VEE object that is more detailed than an icon. Most object open views have fields that allow you to modify the operation of the object.


Operate

The action of an object processing data and outputting a result. An object operates when its data and sequence input pins have been activated. See Activate.


Operator Interface

The interface that the VEE programmer creates to allow the operator (end-user) to control the program. A typical operator interface involves panel views and dialog boxes.


Outline Box

A box that represents the outer edges of an object or set of objects and indicates where the object(s) will be placed in the work area.


Palette

The set of possible colors available in VEE.


Panel Driver

An instrument control object that forces all the function settings in the corresponding physical instrument to match the settings in the control panel displayed in the open view of the object.


Panel View

The view of a VEE program, a UserObject, or a UserFunction that shows only those objects needed for the user to run the program and view the resulting data. You can use panel views to create an operator interface for your program.


Pin

An external connection point on an object where you can attach a line.


Pointer

The graphical image that maps to the movement of the mouse. The pointer allows you to make selections and provides you feedback on a particular process underway. VEE has pointers of different shapes that correspond to process modes, such as an arrow, cross hairs, and hourglass.


Pop-Up Menu

A menu that is raised by clicking the right mouse button. For example, you can raise the Edit menu by clicking the right mouse button in an empty area within the work area. Or you can raise the object menu by clicking the right mouse button on an inactive area of an object.


PostRun

The set of actions that are performed when the program is stopped.


Preferences

Preferences are attributes of the VEE environment that you can change using the Default Preferences button on the toolbar, or the menu File [image] Default Preferences. For example, you can change the default colors, fonts, and number format.


PreRun

The set of actions that resets the program and checks for errors before the program starts to run.


Program

In VEE, a graphical program that consists of a set of objects connected with lines. The program typically represents a solution to an engineering problem.


Program Explorer

A facility in the VEE window that permits exploration of a program, especially the parts of a program that might not be visible on the physical screen.


Promote

To convert from a data type that contains less information to one that contains more information. See also Data Type and Demote.


Propagation

The rules that objects and programs follow when they operate or run. See also Data Flow.


Properties

Object properties are attributes of VEE objects that you can change using Properties on the object menu. Properties can be changed for the Main, UserObject, and UserFunction windows using Properties on their object menus. Properties include colors, fonts, and titles.


Pterodactyl

Any of various extinct flying reptiles of the order Pterosauria of the Jurassic and Cretaceous periods. Pterodactyl are characterized by wings consisting of a flap of skin supported by the very long fourth digit on each front leg.


Pull-Down Menu

A menu that is pulled down from the menu bar when you position the pointer over a menu title and click the left mouse button.


Radio Button

A diamond-shaped button in VEE dialog boxes that allows you to select a setting that is mutually exclusive with other radio buttons in that dialog box. To select a setting, click on the radio button. To remove the setting, click on another radio button in the same dialog box.


Record

A VEE data type that has named data fields which can contain multiple values. Records are typically used to group related articles of information. However, each record field can contain a different data type. Each field can contain another Record container, a Scalar, or an Array. The Record data type has the highest precedence of all VEE data types. However, data cannot be converted to and from the Record data type through the automatic promotion/demotion process. Records must be built/unbuilt using the Build Record and UnBuild Record objects.


Remote Function

A UserFunction which is callable from the local host. (Remote functions are supported in VEE Pro only.) The Import Library object starts the process on the remote host and loads the UserFunctions into the VEE process on the remote host. You can then call the Remote Function with the Call Function object, or from certain expressions. See also UserFunction, Remote Functions, and Compiled Function.


Restore

To return a minimized window or an icon to its full size as a window or open view by double-clicking on it.


Run

To start the objects on a program or thread operating.


Save

To write a file to a storage device, such as a hard disk.


Scalar

A data shape that contains a single value. See also Data Shape.


Schema

The structure or framework used to define a data record. This includes each field's name, type, shape (and dimension sizes), and mapping.


Screen Dump

A graphical printout of a window or part of a window.


Scroll

The act of using a scroll bar either to move through a list of data files or other choices in a dialog box, or to pan the work area.


Scroll Arrow

An arrow that, when clicked on, scrolls through a list of data files or other choices in a dialog box, or moves the work area.


Scroll Bar

A rectangular bar that, when dragged, scrolls through a list of data files or other choices in a dialog box, or moves the work area.


Select

To choose an object, an action to be performed, or a menu item. Usually you select by clicking with your mouse.


Select Code

A number used to identify the address of a hardware interface. The term "select code" has been superceded by the term Logical Unit.


Selection

1. A menu selection (feature).

2. An object or action you have selected in the VEE window.


Selection Field

A field in an object or dialog box that allows you to select choices from a drop-down list.


Sequence Input Pin

The top pin of an object. When connected, execution of the object is held off until the pin receives a container (is "pinged").


Sequence Ouput Pin

Sequence Output Pin

The bottom pin of an object. When connected, this output pin is activated when the object and all data propagation from that object finishes executing.


Sequencer

An object that controls execution flow through a series of sequence transactions, each of which may call a UserFunction, Compiled Function, or Remote Function. The sequencer is normally used to perform a series of tests by specifying a series of sequence transactions. (The Sequencer is available in VEE Pro only.)


Sleep

An object sleeps during execution when it is waiting for an operation or time interval to complete, or for an event to occur. A sleeping object will allow other parallel threads to run concurrently. Once the event, time interval, or operation occurs, the object will execute, allowing execution to continue.


Startup Directory

See Working Directory.


State

A particular set of values for all of the components related to a VEE instrument panel, which represents the measurement state of an instrument. For example, a digital multimeter uses one state for high-speed voltage readings and a different state for high-precision resistance measurements. See also Instrument Panel.


Status Bar

A line at the bottom of the VEE window where information about the current status of and information about VEE is displayed.


Status Field

A field displaying information that cannot be edited. A status field looks like an entry field, but has a gray background.


Step

The action of operating a VEE program one object at a time (to debug the program). The object that will operate next is indicated by a yellow highlight. VEE provides three ways to step through a program, Step Into, Step Over, and Step Out, to control operation of objects in a UserObject and a UserFunction.


Terminal

The internal representation of a pin that displays information about the pin and the data container held by the pin. Double-click on a terminal to view the container information.


Terminal Area

The areas on the left and right sides of an object where terminals are displayed when Show Terminals is active for that object. The input terminal area is on the left, and the output terminal area is on the right side of an object.


Thread

A set of objects connected by solid lines in a VEE program. A program with multiple threads can run all threads simultaneously.


Title Bar

The rectangular bar at the top of the open view of an object or window, which shows the title of the object or window. You can turn off an object title bar using Properties on the object menu.


Toolbar

The rectangular bar at the top of the VEE window which provides buttons for quick access to frequently used commands. The buttons run commands from menus such as File, Edit, View, Debug, and Device.


Transaction

The specifications for input and output (I/O) used by certain objects in VEE. These include the To File, From File, Direct I/O, and Sequencer objects. Transactions appear as phrases listed in the open view of these objects.


Trig Mode

The Trig Mode is an attribute that determines whether trigonometric values are displayed in degrees, radians, or gradians. Note that VEE automatically converts trigonometric values to radians for calculation purposes.


User-Defined Function

A function that you can create, and then call in a VEE program. You can create three types of user-defined functions that can be called using the Call Function object, or from certain expressions. See also UserFunction, Compiled Function, and Remote Function.


UserFunction

A user-defined function created directly in a UserFunction window or from an existing UserObject. The UserFunction exists in the background of the VEE process, but provides the same functionality as a UserObject. You can call a UserFunction with the Call Function object, or from certain expressions. A UserFunction can be created and called locally, or it can be saved in a library and imported into a VEE program with Import Library. (Import of UserFunctions is supported in VEE Pro only.) See also Compiled Function, Remote Function, and UserObject.


UserObject

An object that can encapsulate a group of objects to perform a particular purpose within a program. A UserObject allows you to use top-down design techniques when building a program, and to build user-defined objects that can be saved in a library and reused.


Variable

A named variable that is either declared or undeclared. Variables can be declared as local, global to context, or global to library using Declare Variable. Local and global variables can have values set at run time without being declared; however, programs run faster with declared variables.


View

VEE can present programs and objects in various views. Programs can appear in detail or open views, objects can appear in open or icon views. See Detail View, Icon, Open View, and Panel View.


Wait

See Sleep.


Window

A rectangular area on the screen that contains a particular application program, such as Agilent VEE.


Windows NT, 2000, and XP

Windows Vista, XP and 2000

Operating systems using a windowing interface, developed by Microsoft Corporation, in which VEE runs. Windows Vista, XP and Windows 2000 systems run 32-bit applications and are characterized by a distinct user/kernel boundary.


Work Area

The area within the Main, UserObject, or UserFunction windows in which you place VEE objects and wire them together to create a VEE program. When you Open a program, it is loaded into the Main window's work area.


Work Space

The space in the VEE application window that contains the programming or editing windows such as Main, UserObject, and UserFunction. These windows contain work areas in which you place VEE objects and wire them together to create a VEE program.


Working Directory

The directory in which VEE runs. For example, "C:\Program Files\Agilent\VEE Pro 8.0" is the default working directory of VEE Pro for Windows. The working directory is sometimes called the "startup directory," because it is specified in the shortcut used to start VEE.


XEQ Pin

A pin that forces the operation of the object, even if the data or sequence input pins have not been activated. Only available on the Collector and Sample & Hold objects. See also Control Pin, Data Input Pin, and Sequence Input Pin.


About .NET Errors in VEE

About .NET Errors in Agilent VEE Pro

VEE provides all of the information that .NET passes it. For the most part, a review of the specific .NET method you are using provides you with enough information to determine the nature of the exception. If it does not, you can go straight to the exception type in MSDN.

An example of a verbose exception box where the exception is self-explanatory is:

A less verbose but common error message where the method is the clue is:


Access Array

A menu item.

Use

Use Access Array to access the following array modification objects:

Set Values

Get Values

Set Mappings

Get Mappings

Notes

These objects are usually used after the Allocate Array objects to modify the elements or add mappings to a newly created array.

Location

Data [image] Access Array

See Also

Allocate Array, Get Mappings, Get Values, Set Mappings, Set Values, and Object Menu.

To Extract Values from an Array


Access Record

A menu item.

Use

Use Access Record to access the following record modification objects:

Merge Record

SubRecord

Set Field

Get Field

Notes

These objects are usually used after the Build Record object to modify the elements, merge records or access portions of the record.

Location

Data [image] Access Record

See Also

Build Record, Merge Record, SubRecord, Set Field, Get Field, and Object Menu.

To Change a Field in a Record


Accumulator

An object that displays and outputs a running sum of its input values.

Use

Use Accumulator to keep a running total.

Object Menu

Clear - Clears the contents of the Accumulator.

Note

The type of the accumulated output data is the same as the highest order of the input value. Thus, if the Accumulator is input a Real64 and an Int32, it outputs a Real64.

For example, if the Accumulator data input is activated with a Real64, then later is activated by a Complex, the current accumulated data is Complex; the Accumulator converts the Real64 data to Complex. If one of the inputs is text, all of the data will be converted to text.

Use caution when mixing data types. The order in which they are entered will make a difference in the output. If the inputs are real, real, and text, the Accumulator will add the reals and convert the result to text, then append the input text string to the end of the real string. If the inputs are text, real, and real, the Accumulator will convert the two reals to strings and append them to the end of the text string. Rather than adding the two reals, they will appear as two separate numbers in the accumulated string.

Location

Device [image] Accumulator

See Also

Counter, Properties (Object), and Object Menu.


Activate Breakpoints

When checked, enables all set breakpoints. When not checked, disables all breakpoints.

Use

Use Activate Breakpoints to toggle between debugging and normal program running. When Activate Breakpoints is on, the menu selection is checked. When a breakpoint is encountered, the program stops running.

Notes

The orange (by default) border surrounding the objects with set breakpoints is still present, even when Activate Breakpoints is off. The object Properties shows Set Breakpoint as being checked regardless of the state of Activate Breakpoints.

Breakpoints are only active in VEE 4 and higher execution modes if the Disable Debugging Features box in Default Preferences is not checked. When a breakpoint is set on an object, Step Into will break, Step Over will not break.

Location

Debug [image] Activate Breakpoints

See Also

Clear All Breakpoints, Default Preferences, Properties (Object), Step Into, Step Over, and Toggle Breakpoint.


ActiveX Automation References

Displays the ActiveX Automation References dialog box, which lets you make ActiveX automation libraries available for use in VEE.

Use

Use the ActiveX Automation References dialog box to select the ActiveX automation libraries for VEE to use to control other applications. Libraries appear in this dialog box if their associated applications have been installed so the Windows Registry recognizes them. When you select the libraries you want, press OK to load them into memory for use in VEE, and to search for their object classes, dispatch interfaces, and exported events. You must select type libraries only if you plan to handle events generated by them, or if you want to reference any type libraries so their functionality (properties, methods, enumerations, events) will appear in the Function & Object Browser.

Before referencing type libraries, use the built-in functions CreateObject() or GetObject() to connect with an automation object. Then, after selecting libraries, open VEE’s Function & Object Browser (Device [image] Function & Object Browser) and select ActiveX Objects to generate expressions in Formula objects that manipulate the objects. Use additional Formula expressions to get and set their properties, and call methods.

Dialog Information

Registered Automation Servers: - Contains the list of registered ActiveX automation libraries. Click on a name to highlight it and see information in the status area below the list. Click in the box beside a name, and click OK to select it for use in VEE.

Browse… - If a library exists on your system that does not appear in the list, click Browse to search for it in the Add ActiveX Automation Reference dialog box. When you find and open the library, VEE adds it to the list, and attempts to register it. To use it in VEE, be sure its box is checked, and click OK.

Notes

VEE must be set to VEE 5 or higher execution mode for ActiveX support to take effect (Default Preferences). ActiveX Automation lets you use VEE as an Automation Controller for applications capable of acting as Automation Servers. This lets you interact with applications such as Microsoft Word, Excel, and Access for activities such as sending data from VEE for report generation. This fully supersedes VEE’s current application-control solution, Dynamic Data Exchange (DDE), for automation-capable applications.

An automation library is installed when you install an application that contains it.

Only select as many libraries as you will need for your program to avoid using excessive memory.

For more information about programming techniques that effect the cleanup of ActiveX references, see the CreateObject topic.

Location

Device [image] ActiveX Automation References…

See Also

ActiveX Control References, Default Preferences, Formula, Function & Object Browser, CreateObject, GetObject, an ActiveX Examples

Refer to Help => Contents and Index=> Tell Me About...=> ActiveX

See example programs in the ActiveX example directories
Help [image] Open Example…


ActiveX Control Host

A VEE object that hosts an ActiveX control added to the VEE work area.

Use

The ActiveX Control Host is used as a container for an ActiveX control. When you add a control to the work area (Device [image] ActiveX Controls), VEE creates the container so you have access to the control that is similar to the access available to other VEE objects. The container also gives you access to the control’s specific properties built into it by the control’s developers.

When a control appears in the work area, it has a title and variable name in its title bar. It does not have pins that let you connect it to other objects using lines. You must use expressions referring to the variable name that manipulate the control by getting and setting its properties, and calling methods. VEE’s Function & Object Browser (Device [image] Function & Object Browser) helps you to generate these expressions in Formula objects. The variable name essentially is the declared variable name of the control. The control’s declared variable name is very similar to a variable created using the Declare Variable object, except that the control’s variable is already initialized. The declaration is local-to-context, so by default, the variable name can only be used in the context in which it exists. For information about accessing the ActiveX control globally, see Notes below.

Object Menu

  • Help - Opens this VEE Help topic that describes the container object.

  • Properties - Provides access to the VEE container object’s properties such as title, variable name, colors, fonts, and icon view.

  • Control Properties - Provides access to the control’s property pages that are built in by its developers. Every kind of control has different properties. In the resulting properties window, click the Help button to get more information.

  • Edit Event Handler… - Opens the Edit Event Handler dialog box if any event-handler UserFunctions have been created for the control.

  • Create Event Handler… - Opens the Create Event Handler UserFunction browser. This browser lets you create a UserFunction to handle an event generated by the control. You can create an event handler for each event listed in the browser’s Member area.

Properties (container object)

Title - Displays the container object’s current title and allows you to edit it.

Name - Displays the control’s current local variable name and allows you to edit it. This declares and initializes the control as a local-to-context variable.

Notes

VEE must be set to VEE 5 or higher execution mode for ActiveX support to take effect (Default Preferences). ActiveX controls are available as individual products or may be installed as part of a larger application.

VEE does not support all ActiveX controls. If a control is incompatible with VEE, an error will occur when you add the control to your program or while you are using it.

When you add a control to the VEE work area, it appears with an assigned local variable name in its title bar. You can change the assigned variable name by double-clicking the control’s title bar to get the ActiveX Control Properties dialog box. In the Design category, change value of Name. Since the control has no pins to connect with lines to other objects in your program, you must manipulate the control using expressions in Formula objects that refer to the control by its variable name. Since the variable is local-to-context, these expressions must appear in the same context as the control.

If you want the variable name to be global, then declare a new variable name using Declare Variable (Data [image] Variable [image] Declare Variable). Since the control’s variable name already exists, you cannot simply declare it as global; VEE does not allow such conflicts. In Declare Variable, enter the variable name, set Scope to Global, and set Type: to Object. You do not need to check Specify Object Type; however, by specifying the object type details, VEE will do type checking automatically to assure that the specified Library and Class are assigned only to the declared variable. Then you can set the control’s local variable (such as Calendar1) equal to the declared variable (such as g_calendar1) as shown in this expression:

Set g_calendar1 = Calendar1

Location

Device [image] ActiveX Controls

See Also

ActiveX Control References, Declare Variable, Default Preferences, Formula, Function & Object Browser, ActiveX Examples

Refer to Help => Contents and Index=> Tell Me About...=> ActiveX

See example programs in the ActiveX example directories
Help [image] Open Example…


ActiveX Control References

Displays the ActiveX Control References dialog box, which lets you make ActiveX controls available for use in VEE.

Use

Use the ActiveX Control References dialog box to select the ActiveX controls that you want to use in your VEE program. Controls appear in this dialog box if they or their associated applications have been installed so the Windows Registry recognizes them. When you select the controls you want, press OK to load them into memory for use in VEE, and to search for their object classes, dispatch interfaces, and exported events.

After selecting controls, use Device [image] ActiveX Controls to pick a control and place it in your program’s detail view as you do for any other VEE object. The resulting control "object" appears with a variable name in its title bar. Since controls have no pins like other objects, you must manipulate it using the control’s variable name in Formula expressions. VEE’s Function & Object Browser (Device [image] Function & Object Browser) helps to generate these expressions.

Dialog Information

Registered Controls: - Contains the list of registered ActiveX control type libraries. Click on a name to highlight it and see information in the status area below the list. Click in the box beside a name, and click OK to select it for use in VEE.

Browse… - If a control exists on your system that does not appear in the list, click Browse to search for it in the Add ActiveX Control Reference dialog box. When you find and open the control, VEE adds it to the list, and attempts to register it. To use it in VEE, be sure its box is checked, and click OK.

Notes

VEE must be set to VEE 5 or higher execution mode for ActiveX support to take effect (Default Preferences). ActiveX controls are available as individual products or may be installed as part of a larger application.

Only select as many controls as you will need for your program to avoid using excessive memory.

After you select names using the ActiveX Control Reference dialog box, VEE adds control names to the menu Device [image] ActiveX Controls. It is normal for some selections to result in more than one ActiveX control being added to the menu.

VEE does not support all ActiveX controls. If a control is incompatible with VEE, an error will occur when you add the control to your program or while you are using it.

Location

Device [image] ActiveX Control References…

See Also

ActiveX Automation References, ActiveX Controls, Declare Variable, Default Preferences, Formula, Function & Object Browser, ActiveX Examples Refer to Help => Contents and Index=> Tell Me About...=> ActiveX

See example programs in the ActiveX example directories
Help [image] Open Example…


ActiveX Controls

A Device menu choice that lets you add ActiveX controls to the VEE work area.

Use

Use the ActiveX Controls menu to add the ActiveX controls that are available for VEE to use. Controls appear in the cascading menu if they were selected using the ActiveX Controls Reference dialog box (Device [image] ActiveX Controls Reference…).

Notes

VEE must be set to VEE 5 or higher execution mode for ActiveX support to take effect (Default Preferences). ActiveX controls are available as individual products or may be installed as part of a larger application.

VEE does not support all ActiveX controls. If a control is incompatible with VEE, an error will occur when you add the control to your program or while you are using it.

Location

Device [image] ActiveX Controls

See Also

ActiveX Control Host, ActiveX Control References, Default Preferences, ActiveX Examples Refer to Help => Contents and Index=> Tell Me About...=> ActiveX

See example programs in the ActiveX example directories
Help [image] Open Example…


Add Days

Adds days to the given date time.

Location

System [image] DateTime [image] Add Days


Add Hours

Adds hours to the given date time.

Location

System [image] DateTime [image] Add Hours


Add Minutes

Add minutes to the given date and time .

Location

System [image] DateTime [image] Add Minutes


Add Months

Adds months to the given date time.

Location

System [image] DateTime [image] Add Months


Add Seconds

Adds seconds to the to the given date and time.

Location

System [image] DateTime [image] Add Seconds


Add Terminal

A menu item.

Use

Use Add Terminal to access the following features which add terminals:

Data Input

Control Input

Data Output

Error Output

Short Cuts

You can quickly add a data terminal by placing the cursor over the input or output terminal display area and then pressing CTRL+A. Each press of CTRL+A inserts an additional data terminal where the cursor is located.

Location

On each object menu [image] Add Terminal

See Also

Properties (Object), Line Probe, Delete Terminal, Control Input (Object Menu), Data Input (Object Menu), Data Output (Object Menu), and Error Output (Object Menu).

To Add Input and Output Terminals to a UserObject

To Automatically Re-Scale the Display

To Select a File Name Programmatically


Add To Panel

Copies the selected objects to the associated context panel of your VEE program.

Use

Use Add To Panel to place a set of selected objects on the panel view to create a user interface for your program. For example, the panel view might include only the input and display objects for a program; the detail view of the program is not displayed.

When a panel view exists and the program is not secured, there are two buttons on a UserObject's or UserFunction's title bar that allow you to toggle to the desired view.

If you select Add To Panel and a panel view does not exist, it is created.

Notes

The Add To Panel feature is not available if no objects are selected.

The panel view of a UserObject may be added to the Main panel view or the panel view of a UserObject that is a surrounding context. In other words, panels can be nested. When panels are added to parent panels, an exact duplicate of the source panel is generated. Whenever the source panel is modified, all duplicate panels are updated as well.

To add a UserObject panel to a parent panel, such as the Main panel:

1. After creating a UserObject and its panel, right-mouse click on the UserObject’s icon view to get its object menu.

2. Click on Restore to get the open view. It appears like a panel view. Do not delete this or you will delete the UserObject from the parent program.

3. Select the UserObject so it is highlighted.

4. Click on the Add To Panel toolbar button (Edit [image] Add To Panel). The UserObject appears in the parent panel.

Location

Edit [image] Add To Panel

Or UserObject object menu Edit [image] Add To Panel

See Also

Create UserObject, Delete (Object Menu), Create RunTime Version, Select All, View Detail, and View Panel.

To Add a UserObject Panel to the Main Panel

To Add Objects to a Nested UserObject Panel

To Add Objects to a Panel

To Build a UserFunction Panel

To Build a UserObject Panel


Add Years

Adds years to the given date time.

Location

System [image] DateTime [image] Add Years


Advanced Instrument Properties

A dialog box that allows you to configure instrument device drivers and interface communications parameters.

Use

After you have selected an Interface: type (GPIB, Serial, etc.) using the Instrument Properties dialog box, clicking on the Advanced... button will bring up the Advanced Instrument Properties dialog box.

There are six different versions of the Advanced Instrument Properties dialog box, one for each of the following types of interfaces:

1. GPIB

2. Serial

3. GPIO

4. VXI

5. TCPIP

6. USB

Dialog Information

The Advanced Instrument Properties dialog box provides the following tabs and fields:

Note
Each type of interface, (GPIB, Serial, GPIO, VXI, TCPIP, or USB) does not always require all of the same communications parameters. For example, the Direct I/O tab for a GPIO interface configuration will contain only a subset of the fields that are present on the Direct I/O tab for a GPIB interface configuration. The following tab descriptions present all of the possible fields that can be found on any particular type of tab.

General tab:

Timeout (sec): - Allows you to specify how many seconds VEE will wait for an instrument to respond to a communication request before generating an error. The default is 5 seconds.

Live Mode: - Specifies whether Live Mode is ON or OFF. If Live Mode is off, you can run your VEE program even if your instrument is not connected. However, to actually communicate with the instrument, Live Mode must be ON. Live Mode remains OFF until you enter a non-zero address in the Address field of the Instrument Properties dialog box; then, Live Mode switches to ON. You can then toggle the ON or OFF field by clicking on it. Live Mode does not apply to Plug&play and IVI-COM Drivers.

Byte Ordering: - Specifies the byte order the device uses for reading and writing binary data. VEE determines if byte swapping is necessary. Click on this field to choose between MSB (send Most-Significant Byte, first) and LSB (send Least-Significant Byte, first). All IEEE 488.2-compliant devices use the MSB order. MSB is also the default. Refer to your instrument manual for more specific information.

Description (optional): - Allows you to enter your own brief alphanumeric identifier for the instrument.

Direct I/O tab:

Read Terminator: - Allows you to specify the characters used to terminate an instrument's Read transaction. The default termination character is \n (newline).

Write - Allows you to specify several parameters of an instrument write transaction. There are five fields which can be edited to specify these parameters. These fields are:

EOL Sequence: - Allows you to specify the characters used to identify an EOL (End Of Line). The default characters are \n.

Multi-Field as: - Choices are Data Only (default), and (...) Syntax.

Array Separator: - Allows you to specify the character used as an Array Separator. The default character is "," (a comma).

Array Format: - Choices are Linear or Block. The default is Linear.

END (EOI) on EOL: - End Or Identify on End Of Line. The choices are YES or NO. The default is NO.

Conformance: - Allows you to specify which GPIB IEEE conformance specification will be used in the Direct I/O transaction. The choices are, IEEE 488 (default), and IEEE 488.2.

Binblock: - Allows you to specify the Binblock format for a Direct I/O transactions. The Binblock format choices are:

None - If you specified Conformance (above) to be IEEE 488.2, this will be the default choice.

#A - An IEEE 728 block header with the format: #A<Byte_Count><Data>

#I - An IEEE 728 block header with the format: #I<Byte_Count><Data>

#T - An IEEE 728 block header with the format: #T<Data><END>

Where:

- # is the actual character.
- A, I and T are the actual characters.
- <Byte_Count> consists of two bytes which together form a 16-bit unsigned integer that specifies the number of bytes that follow in <Data>. (VEE calculates this automatically).
- <Data> is a stream of arbitrary bytes.
- <END> indicates that EOI is asserted with the last data byte transmitted.

State (Learn String): - The State field indicates whether or not the instrument has been configured for uploading and downloading learn strings. The choices are Not Config'd (which is the default value), or Configured. If you choose Configured then the Upload String and Download String fields will be highlighted for an input.

Upload String: - The Upload String field specifies the command that is sent to the instrument when you select the Upload State from the Direct I/O object menu. Specify the command that causes the instrument to output its learn string; consult your instrument programming manual for details. Note that you must enclose the command with double quotes.

Download String: - The Download String field specifies the string that is sent to the instrument immediately before the learn string as the result of a WRITE STATE (LEARN STRING) transaction in a Direct I/O object. This field is provided to support instruments that require a command prefix when downloading a learn string; consult your instrument programming manual for details.

Plug&play Driver tab:

Plug&play Driver Name: - The driver name assigned to the Plug&play device being configured. The default name is Unknown.

Parameters to init() call group:

Address (eg GPIB-VXI0::12::INSTR): - The device address of the Plug&play instrument.

Perform Identification Query - When this box is checked, a query of the Plug&play device ID will be performed at initialization. The box is checked by default.

Perform Reset - When this box is checked, the device will automatically be sent a Reset command. The box is checked by default.

IVI-COM Driver tab:

IVI-COM Driver/Session Name: - The name of the IVI-COM driver or IVI Config Store session.

Address: - The address of the instrument. This field is empty when a session name is offered.

Perform Identification Query: - Performs an identification string, such as an *IDN.

Perform Reset: - Resets the instrument.

Use Class Compliant Interface: - IVI has definitions for different instrument classes such as DMM or Scope. When you check this checkbox, you are switching from a device specific IVI driver (the default) which has information specific to the manufacturer to a class specific IVI driver that is manufacturer independent.

Configure IVI Driver Session: - Selecting this button launches the Instrument Explorer. The Instrument Explorer uses the IVI Config Store to find instruments. Using Instrument Explorer, you can define IVI sessions that contain the resource string and other parameters for the instrument. For other information about the Instrument Explorer and what it does, please refer to its online help.

Panel Driver tab:

ID Filename: - Clicking on this field will bring up the Read from what Instrument Driver? dialog box. From the Read from what Instrument Driver? dialog box, you can select the desired ID Filename from the directories and files that are displayed.

Sub Address: - Enter the Sub Address (if any) of the Panel Driver.

Error Checking: - Turns Error Checking ON or OFF. Default is ON.

Incremental Mode: - Turns Incremental Mode ON or OFF. Default is ON.

Serial tab:

Baud Rate: - The default baud rate is 9600 (bits per second).

Character Size: - The default is 8(bits). Allowed values are 5, 6, 7, 8, and None.

Stop Bits: - The default is 1. Allowed values are 1 and 2.

Parity: - The default is None. Allowed values are None, Odd, Even, Mark, and Space.

Handshake: - The default is None. Allowed values are None and Xon/Xoff.

Receive Buffer Size: - The default is 4096 (bytes).

GPIO tab:

Data Width: - The Data Width field specifies the number of bits of parallel data transmitted as a unit across the GPIO interface. This field configures the interface to read and write data either 8 bits (the default value), or 16 bits wide. No hardware switches need to be set in conjunction with this field.

A16 Space tab: (VXI Only)

Byte Access (D8) - The Byte Access field specifies whether the VXI device supports 8-bit, A16 memory accesses. The Byte Access choices are:

NONE - The device does not support byte access. This is the default.

ODD ACCESS - The device supports byte access, but only on odd-byte boundaries (D08(O)).

ODD/EVEN ACCESS - The device supports byte access on all boundaries (D08(E)).

Word Access (D16) - The Word Access field is not editable. All VXI devices must support 16-bit access (D16).

LongWord Access (D32) - The LongWord Access field specifies whether the VXI device supports 32-bit, A16 memory accesses. The LongWord Access choices are:

NONE - The device does not support 32-bit access. This is the default.

D32 ACCESS - The device supports 32-bit, A16 memory access.

Add Register - Each time you click on the Add Register field, a row of new fields will appear on the right half of the dialog box. Each of these new fields allow you to configure access to a device's A16 memory. The four fields are:

Name - This is the symbolic name of the register, which is used to refer to the particular register in a Direct I/O object using either a READ REGISTER or a WRITE REGISTER transaction.

Offset - This is the offset in bytes from the relative base of the device's A16 memory, for the register being configured. The default Offset is 0.

Format - This is the data format that will be read from, or written to, the register being configured. The read or write access will take place at the byte specified in the Offset field. The possible formats are:
- BYTE - Read or write a byte. The device must support and be configured correctly for 8-bit access by using the Byte Access field explained above. If the BYTE field is ODD, the byte location specified in the Offset field must be an odd number.
- WORD16 - Read or write a 16-bit word. The 16 bits are represented as a two's complement integer. All VXI devices explicitly support this format.
- WORD32 - Read or write a 32-bit word. The 32 bits are represented as a two's complement integer. VEE supports this format even if the LongWord Access field is specified as NONE (by using two D16 accesses to read or write all 32 bits). If the LongWord Access field is specified as D32 ACCESS, all 32 bits are accessed.
- REAL32 - Read or write a 32-bit word which is represented as an IEEE 754 32-bit floating-point number. VEE supports this format even if the LongWord Access field is specified as NONE (by using two D16 accesses to read or write all 32 bits). If the LongWord Access field is specified as D32 ACCESS, all 32 bits are accessed.

Mode - Specify what I/O mode the register will support. The choices are:
- READ - This register will appear as a choice in a READ REGISTER transaction only.
- WRITE - This register will appear as a choice in a WRITE REGISTER transaction only.
- READ/WRITE - This register will appear as a choice in both a READ REGISTER and WRITE REGISTER transaction.

Delete Register - When you click on the Delete Register field, a Select Register To Delete box will appear which contains the symbolic Name of each of the currently configured registers. Click on the symbolic Name of the register you wish to delete, then click the OK button to confirm the deletion.

A24/A32 Space tab: (VXI Only).

The A24/A32 Space refers to the A24 or A32 extended memory in a VXI device. A VXI device can implement either A24 memory or A32 memory, but not both.

Byte Access (D8) - The Byte Access field specifies whether the VXI device supports 8-bit, extended memory accesses. The Byte Access choices are:

NONE - The device does not support byte access. This is the default.

ODD ACCESS - The device supports byte access, but only on odd-byte boundaries (D08(O)).

ODD/EVEN ACCESS - The device supports byte access on all boundaries (D08(E)).

Word Access (D16) - The Word Access field is not editable. All VXI devices must support 16-bit access (D16) for all memory spaces.

LongWord Access (D32) - The LongWord Access field specifies whether the VXI device supports 32-bit extended memory accesses. The LongWord Access choices are:

NONE - The device does not support 32-bit access. This is the default.

D32 ACCESS - The device supports 32-bit extended memory access.

Add Location - Each time you click on the Add Location field, a row of new fields will appear on the right half of the dialog box. Each of these new fields allow you to configure access to a device's extended memory. The four fields are:

Name - This is the symbolic name of the location, which is used to refer to the particular memory location in a Direct I/O object using either READ MEMORY or WRITE MEMORY transactions.

Offset - This is the offset in bytes from the relative base of the device's extended memory, for the location being configured. The default Offset is 0.

Format - This is the data format that will be read from, or written to, the location being configured. The read or write access will take place at the byte specified in the Offset field. The possible formats are:
- BYTE - Read or write a byte. The device must support and be configured correctly for 8-bit access by using the Byte Access field explained above. If the BYTE field is ODD, the byte location specified in the Offset field must be an odd number.
- WORD16 - Read or write a 16-bit word. The 16 bits are represented as a two's complement integer. All VXI devices explicitly support this format.
- WORD32 - Read or write a 32-bit word. The 32 bits are represented as a two's complement integer. VEE supports this format even if the LongWord Access field is specified as NONE (by using two D16 accesses to read or write all 32 bits). If the LongWord Access field is specified as D32 ACCESS, all 32 bits are accessed.
- REAL32 - Read or write a 32-bit word which is represented as an IEEE 754 32-bit floating-point number. VEE supports this format even if the LongWord Access field is specified as NONE (by using two D16 accesses to read or write all 32 bits). If the LongWord Access field is specified as D32 ACCESS, all 32 bits are accessed.

Mode - Specify what I/O mode the location will support. The choices are:
- READ - This location will appear as a choice in a READ MEMORY transaction only.
- WRITE - This location will appear as a choice in a WRITE MEMORY transaction only.
- READ/WRITE - This location will appear as a choice in both a READ MEMORY and WRITE MEMORY transaction.

Delete Location - When you click on the Delete Location field, a Select Memory Location To Delete box will appear which contains the symbolic Name of each of the currently configured locations. Click on the symbolic Name of the location you wish to delete, then click the OK button to confirm the deletion.

Location

I/O [image] Instrument Manager... then select Add... or Properties then select Advanced...

See Also

Instrument Properties, Instrument Manager.

To Add an Instrument Configuration

To Use a Direct I/O Object


Advanced I/O

A menu item.

Use

Use Advanced I/O to access the following objects for low-level control of the GPIB, RS-232 (serial), VXI, LAN, and USB interfaces (such as bus commands, polling, and service requests):

Interface Operations

Device Event

Interface Event

MultiDevice Direct I/O

Notes

VXIplug&play does not support any of the Advanced I/O features.

Location

I/O [image] Advanced I/O

See Also

Agilent IO Monitor, Device Event, Interface Event, Interface Operations, and MultiDevice Direct I/O.

To Poll GPIB Instruments


Align

An Edit menu selection that allows you to physically Align objects in your VEE Panel and Detail views.

Use

Align provides several options for manipulating the physical placement of VEE objects. The options control horizontal and vertical alignment, as well as the distribution of the objects. You can hold down the CTRL key and simultaneously use the left mouse button to select the objects you wish to Align. You can also hold down the CTRL key and draw a box around the objects you wish to align by using the left mouse key and dragging from the upper left to the lower right corner of the selection area. Finally, if you want to select all of the objects, you can go the Edit Menu and choose Select All. Once you have selected the objects, use one of the following menu options to perform the alignment.:

  • Middles - Performs a horizontal alignment of the selected VEE objects using the middle of the left-most object as a Y coordinate reference point.

  • Tops - Performs a horizontal alignment of the selected VEE objects using the top of the left-most object as a Y coordinate reference point.

  • Bottoms - Performs a horizontal alignment of the selected VEE objects using the bottom of the left-most object as a Y coordinate reference point.

  • Centers - Performs a vertical alignment of the selected VEE objects using the center of the top-most object as an X coordinate reference point.

  • Lefts - Performs a vertical alignment of the selected VEE objects using the left side of the top-most object as an X coordinate reference point.

  • Rights - Performs a vertical alignment of the selected VEE objects using the right side of the top-most object as an X coordinate reference point.

  • Distribute Horizontally – Performs a horizontal distribution of the selected VEE objects by using the left side of the left most object and evenly distributing the objects on the horizontal plane.

  • Distribute Vertically - Performs a vertical distribution of the selected VEE objects by using the top of the topmost object you select and evenly distributing the objects on the vertical plane.

Notes

If, when aligning an object, its new placement would cause it to overlap an object, use the Bring-to-Front or Send-to-Back feature to rearrange the object as needed.

Aligned objects are not unselected after an alignment has occurred. This allows a subsequent group alignment of those same objects.

The reference object is not moved during an alignment or distribution.

Location

Edit [image] Align

Middles or

Tops or

Bottoms or

Centers or

Lefts or

Rights or

Distribute Horizontally

Distribute Vertically

See Also

Default Preferences, Bring to Front (Object Menu), Send to Back (Object Menu), and Select All


Allocate Array

A menu item.

Use

Use Allocate Array to access the following array building and initialization objects:

Alloc Text

Alloc UInt8

Alloc UInt16

Alloc Int16

Alloc Int32

Alloc Int64

Alloc Real32

Alloc Real64

Alloc Coord

Alloc Complex

Alloc PComplex

Notes

Use Set Values to modify arrays that already exist.

Location

Data [image] Allocate Array

See Also

Alloc Coord, Alloc Complex, Alloc UInt8, Alloc Int16, Alloc Int32, Alloc PComplex, Alloc Text, Alloc Real32, Alloc Real64, Get Values, Set Mappings, and Set Values.

To Allocate an Array

To Change Values in an Array

Object Menu


Alloc Boolean

An object that creates a Boolean array.

Use

Use Alloc Boolean to create an array of Boolean elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value | Lin Ramp | Log Ramp

Init Value - The values to place in each array element. This value is interpreted as a Boolean. Default is False.

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the value of the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] Boolean

See Also

Boolean, Get Values, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


Alloc Complex

An object that creates a Complex array.

Use

Use Alloc Complex to create an array of Complex elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value - The value to place in each array element. Default is (0, 0).

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the value of the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] Complex

See Also

Complex, Get Values, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), Object Menu


Alloc Coord

An object that creates a Coord array.

Use

Use Alloc Coord to create an array of Coord elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Unlike other array types such as Int32 and Real64, Num Dims can only be 1 since Coord arrays of greater than 1 dimension are not allowed in VEE.

Num Coord Dims - The number of values in each Coord. Valid range is 2 to 10.

Init Value - The value to place in each array element. Default is (0, 0), (0,0,0), (0,0,0,0), etc. depending on the value of Num Coord Dims.

Size - The number of elements in the dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

Location

Data [image] Allocate Array [image] Coord

See Also

Allocate Array, Build Data, Coord, Get Values, Set Values, and UnBuild Data.

To Allocate an Array, Properties (Object), and Object Menu


Alloc Int16

An object that creates an integer array.

Use

Use Alloc Int16 to create an array of 2-byte integer elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value | Lin Ramp | Log Ramp

Init Value - The values to place in each array element. This value is interpreted as an integer. Default is 0.

Lin Ramp - A linear ramp of integer values that are as equally spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Log Ramp - A ramp of integer values that are as logarithmically spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the value of the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] Int16

See Also

Int16, Get Values, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


Alloc Int32

An object that creates an integer array.

Use

Use Alloc Int32 to create an array of 4-byte integer elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value | Lin Ramp | Log Ramp

Init Value - The values to place in each array element. This value is interpreted as an integer. Default is 0.

Lin Ramp - A linear ramp of integer values that are as equally spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Log Ramp - A ramp of integer values that are as logarithmically spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the value of the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] Int32

See Also

Int32, Get Values, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


Alloc Int64

An object that creates an integer array.

Use

Use Alloc Int64 to create an array of 8-byte integer elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value | Lin Ramp | Log Ramp

Init Value - The values to place in each array element. This value is interpreted as an integer. Default is 0.

Lin Ramp - A linear ramp of integer values that are as equally spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Log Ramp - A ramp of integer values that are as logarithmically spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the value of the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] Int64

See Also

Int64, Get Values, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


Alloc PComplex

An object that creates a PComplex array.

Use

Use Alloc PComplex to create an array of PComplex elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value - The value to place in each array element. The initial value's phase is normalized to fall between pi and -pi radians; if the number's magnitude is negative, it is converted to a positive by shifting the phase angle 180 degrees. Default is (0, @0).

Size - The number of elements in the dimension. There is one field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

Set Values changes the values of individual elements.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] PComplex

See Also

Allocate Array, Get Values, PComplex, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


Alloc Real32

An object that creates a real array.

Use

Use Alloc Real32 to create an array of 4-byte real elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value | Lin Ramp | Log Ramp

Init Value - The value to place in each array element. Default is 0.

Lin Ramp - A linear ramp of real values that are as equally spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Log Ramp - A ramp of real values that are logarithmically spaced between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] Real32

See Also

Get Values, Real32, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


Alloc Real64

An object that creates a real array.

Use

Use Alloc Real64 to create an array of 8-byte real elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value | Lin Ramp | Log Ramp

Init Value - The value to place in each array element. Default is 0.

Lin Ramp - A linear ramp of real values that are as equally spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Log Ramp - A ramp of real values that are logarithmically spaced between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] Real64

See Also

Get Values, Real64, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


Alloc Text

An object that creates a Text array.

Use

Use Alloc Text to create an array of Text elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value - The value to place in each array element. This value is interpreted as a string. Default is null (an empty string).

Size - The number of elements in the dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] Text

See Also

Get Values, Set Mappings, Set Values, and Text.

To Allocate an Array, Properties (Object), and Object Menu


Alloc UInt8

An object that creates an integer array.

Use

Use Alloc UInt8 to create an array of 1-byte integer elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value | Lin Ramp | Log Ramp

Init Value - The values to place in each array element. This value is interpreted as an integer. Default is 0.

Lin Ramp - A linear ramp of integer values that are as equally spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Log Ramp - A ramp of integer values that are as logarithmically spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the value of the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] UInt8

See Also

UInt8, Get Values, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


Alloc UInt16

An object that creates an integer array.

Use

Use Alloc UInt16 to create an array of 2-byte integer elements.

Open View Parameters

Num Dims - The number of dimensions in the output array. Num Dims is an integer from 1 through 10. Default is 1.

Init Value | Lin Ramp | Log Ramp

Init Value - The values to place in each array element. This value is interpreted as an integer. Default is 0.

Lin Ramp - A linear ramp of integer values that are as equally spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Log Ramp - A ramp of integer values that are as logarithmically spaced as possible between the ramp initial value (inclusive) and the ramp ending value (inclusive). This option is only available if Num Dims = 1.

Size - The number of elements in the dimension. There is one size field per dimension. Default is 10.

Init Value and Size may be set on the object or from data input pins.

Notes

To change the values of individual elements, use Set Values.

If the Num Dims value is changed, the view automatically creates or deletes fields on the open view so that the number of dimension size fields matches the value of the Num Dims value.

The output array is not mapped. Use Set Mappings to map the dimensions of the array.

Location

Data [image] Allocate Array [image] UInt16

See Also

UInt16, Get Values, Set Mappings, and Set Values.

To Allocate an Array, Properties (Object), and Object Menu


AlphaNumeric

An object that displays alphanumeric data.

Use

Use AlphaNumeric to display any of the data types as a single value, an Array 1D, or a Array 2D. To view an array, scroll the display with the scroll bars.

Properties

ShowArrayIndices - When this property is True and the data received is an array, each line in the display area is indexed. Default is True.

Number Format - If Global format is checked, use the default format. Default is on.

Integer: - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Real: - If Global Format is off, specify the number format for Real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Sat 01/Jan/2003 17:01:38). Default is Standard.

Significant Digits: - If Global Format is off, specify the number of significant digits to display for Real values.

Notes

A row of asterisks (***) is displayed if the current width of the AlphaNumeric object is too small to display the default precision of the numeric type (using the currently specified display font). Resize the object to display the data.

If there is a 2D Array, you will see a scroll bar (unless you have resized the object to show the entire array).

Arrays that are three-dimensional and larger are displayed as the string 3D Array and so forth.

The display of ASCII values 0-31 is dependent on font and may not be readable.

Text strings longer than 2048 characters may not display properly on some platforms (operating systems). Text strings longer than 32767 characters do not display properly on any platform.

Location

Display [image] AlphaNumeric

See Also

Default Preferences and Logging AlphaNumeric.

To Display a Scalar Value and Properties (Object)

To Display an Array of Values and Object Menu


Arrange Icons

A Windows menu selection which controls the arrangement of minimized window icons in the VEE workspace.

Use

Use Arrange Icons to access the following icon placement functions:

by Position - this selection will arrange all minimized window icons along the bottom of the VEE workspace based on their current positions.

by Name - this selection will lexicographically arrange all minimized window icons along the bottom of the VEE workspace.

Notes

The Arrange Icons menu item will be unavailable (grayed out) if there are no open, minimized windows.

Location

Window [image] Arrange Icons

See Also

Minimize All, by Name, and by Position.


ArrayList - Add

Add an item to an array, list, or collection.

Location

System [image] Collections [image] ArrayList [image] Add


ArrayList - Clear

Clear the items in the array, list, or collection.

Location

System [image] Collections [image] ArrayList [image] Clear


ArrayList - Contains Item?

Checks to see when the array, list, or collection contains a given item.

Location

System [image] Collections [image] ArrayList [image] Contains


ArrayList - Count

Count the items in the array, list, or collection.

Location

System [image] Collections [image] ArrayList [image] Count


ArrayList - Create

Creates a new array, list, or collection.

Location

System [image] Collections [image] ArrayList [image] Create


ArrayList - Enumerate

Enumerates the members of an array, list, or collection.

Location

System [image] Collections [image] ArrayList [image] Enumerate Items


ArrayList - Get

Gets an item from an array, list, or collection.

Location

System [image] Collections [image] ArrayList [image] Get Item


ArrayList - Remove Item

Removes an element from an array, list, or collection.

Location

System [image] Collections [image] ArrayList [image] Remove


ArrayList - Set Item

Sets an existing value to a new value in an array, list, or collection.

Location

System [image] Collections [image] ArrayList [image] Set Item


asClrType

asClrType(x, t)

A function that converts a VEE data container “x” to a .NET object of type “t”.

Use

Use asClrType to convert a VEE data container to a .NET object of type “t”. VEE converts data types between VEE and .NET automatically for all data types that both VEE and .NET support natively. For example, Int16, Int32, Real64, etc. This is a design decision that should satisfy most VEE use cases. In less frequent use cases, you may wish to “undo” this automatic conversion so you can use the data as a true .NET object. In those cases, you can use asClrType type conversion function to convert a VEE data type to a .NET/CLR object.

“x” is a VEE data container. The allowed VEE data container types are Boolean, Uint8, Int16, Int32, Int64, Real32, Real64, Text and arrays of those types. “t” is a .NET/CLR type. The allowed .NET/CLR data types include all the primitive types (System.Boolean, System.Byte, System.Sbyte, System.Int16, System.Uint16, System.Int32, System.Uint32, System.Int64, vUint64, System.Char, System.Double, and System.Single), System.Decimal, System.DateTime and System.String.

Returns a .NET object of type “t”. An error 440 will occur if either the VEE data container or the .NET/CLR type is not allowed. An error 464 will occur if the conversion fails.

Assumption: You have referenced the assembly mscorlib.dll. This assembly provides all the .NET/CLR data types allowed for this function.

Examples

VEE automatically converts the .NET type System.String to VEE’s Text. If you want to use the many useful functions in the System.String class, you may use asClrType to convert the text back to System.String:

Set dotnetString = asClrType(“abacusabcus”, System.String);

dotNetString.EndsWith(“us”);

Also see examples\DotNet\StringSplit.vee.

Location

Device [image] Function & Object Browser

> Built-in Functions

> Type Conversion

> asClrType


Auto Scrolling

In Detail view, drag but don't drop an Object to the edge of the main work area and pause, the work area will scroll in that direction. You can move the Object to any edge or corner.


Beep

An object that generates an audible tone.

Use

Use Beep to generate a tone of a specified frequency, duration, and volume.

Open View Parameters

Frequency (Hz) - The frequency of the tone in Hertz. Default is 1000 Hz.

Duration (sec) - The time in seconds for the tone to last. Default is 0.1 sec.

Volume (0-100) - The relative volume of the tone, where 0 is silent and 100 is the loudest. Default is 80. (On the PC, any value from 1 to 100 causes the same volume. However, a value of 0 causes silence.) This parameter is ignored for all versions of Windows.

All of the three open view parameters can be added as data input terminals.

Notes

The functionality of the Beep object is hardware dependent. In some cases, one or more of the open-view parameters may not affect the actual tone generated. Also, some computers do not have internal speakers and may require an external speaker module. Refer to your computer owner's manual for information about its audio output capabilities.

A Frequency or Volume value less than or equal to zero will pause for the specified duration.

The Beep object may complete execution (activate its sequence output pin) before a long duration tone has completed. Execution of subsequent Beep objects, however will pause program execution until the previous tone has completed.

Frequency and volume are ignored on Windows XP/2000/Vista.

Location

Display [image] Beep

See Also

Properties (Object) and Object Menu


Boolean

An object that outputs a constant Boolean scalar or 1 D Array.

Use

Use Boolean to set a Boolean constant or to get user input. Click on the entry field to enter a value.

Operations supported between Booleans are:

  • Logical operation: AND, OR, XOR, NOT(!)

  • Comparison operation: ==, !=

The following table shows the differences between Execution mode 8 and other Execution modes for Boolean data type.

Operations | ExecMode VEE 8 | ExecMode VEE 7 | ExecMode VEE 6 | ExecMode VEE 4&5
Type of TRUE, FALSE | Boolean | Int32 | Int32 | not supported
.NET or COM assignments Example: TreeView.ShowLines = TRUE | support | not supported | not supported | not supported
Logical operations between Boolean and other data types: OR, NOT, XOR, AND Example: TRUE OR 0.0 | not supported | support | support | not supported
Math operations: Example: sin(true) | not supported | support | support | not supported
Basic math operations: +, -, *, / Examples: 1 + True, True + False | not supported | support | support | not supported

Example

To use Boolean as a prompt on a panel view, change the name of the Boolean object to a prompt. The user fills in the requested information in the entry field.

Properties

 DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are scalar and Array 1D.

 ArraySize - When DataShape 1D Array is selected, ArraySize sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D Array is selected.

Stepping Category - Disabled when DataShape is Array 1D.

 ShowArrayIndices - When this property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is True.

 Wait for Input - When this property is True, the object does not operate until the object's value is changed. When the property is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When this property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

 InitialValue - Specifies the value to be set. Default value is False.

 InitializeAtPreRun - When this property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When this property is True, the Initial Value is set at Activate time. Default is False.

Notes

From version 8.0, Agilent VEE supports Boolean in Compiled Functions. The user can use VEE_BOOL as the return type and the parameter type of a Complied Function. Agilent VEE treats VEE_BOOL as Boolean.

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin available on most data constants.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires an integer value, either a Scalar or an Array 1D. The Constant is re-configured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to false. If the Constant is configured as an Array 1D, all values are set to false. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Boolean is configured to be an array.

Location

Data [image] Constant [image] Boolean

See Also

Alloc Boolean, Complex, Constant, Coord, Date/Time, Selection Control, Default Preferences, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real32, Real64, Text, and Toggle Control.

To Use a Data Constant


Break

An object that terminates the current iteration loop.

Use

Use Break to stop the loop and continue execution through the sequence output pin of the iterator.

Note

Break is usually used with Until Break objects. It may also be used with other iteration objects and is often used with an If/Then/Else object to conditionally stop iteration.

Location

Flow [image] Repeat [image] Break

See Also

For Count, For Range, For Log Range, Next, On Cycle, If/Then/Else, and Until Break.

To Loop Part of a VEE Program, Properties (Object), and Object Menu


Bring to Front (Object Menu)

Brings an Object to the front of the viewable plane by changing the z-order of the object..

Use

From the Object menu of the Panel view, places the chosen Object in the foreground of the viewable plane.

See Also

Send to Back (Object Menu), Align, and Move (Object Menu)


Build Arb Waveform

An object that creates a waveform from a set of coordinate data.

Use

Use Build Arb Waveform to create a uniformly sampled waveform from an Array 1D of Coord values.

Open View Parameters

Num Points - The number of points in the output waveform. Default is 256. Num Points may be set from a data input.

Notes

Build Arb Waveform uses the following formula:

  dx = (Xmax-Xmin)/Num Points

  Xvalue = Xmin + (point * dx)

Therefore, the last data point is not the last independent value of Coord.

The independent values (x) of each Coord must be greater than, or equal to, the independent value of the previous Coord in the array.

The Input Coord array must be (x,y) pairs, not (x,y,z).

Location

Data [image] Build Data [image] Arb Waveform

See Also

Build Waveform, Comparator, Coord, Function Generator, Noise Generator, Pulse Generator, Properties (Object), and Object Menu

See Examples

ScopeMask.vee


Build Complex

An object that creates a Complex number.

Use

Use Build Complex to create a Complex number from real and imaginary components.

Notes

If one of the inputs is an array, the other input must be either a Scalar or an array of the same size and shape. Both inputs are converted to type Real64. The output is the same size and shape as the inputs. The input values' mappings are ignored and the output Complex value is not mapped.

Location

Data [image] Build Data [image] Complex

See Also

Build Data, UnBuild Complex, Properties (Object), and Object Menu

See Examples

Complex.vee


Build Coord

An object that creates a Coord from real numbers.

Use

Use Build Coord to build a Coord from real components.

Notes

The number of data inputs determines the number of coordinate fields. The default (and minimum) is 2 (x,y). The maximum number of coordinate fields is 10.

If one of the inputs is an array, the other input(s) must be either Scalar or array data of the same size and shape. All inputs are converted to type Real64. The output is of the same shape as the inputs. The input values' mappings are ignored.

The data input shape must be a Scalar or Array 1D.

Note
For Coordinate data type, the field names will always be x, y, z, w, v, u, t, s, r, q even though you may change the input terminal names. These field names are used on UnBuild Coord and sort(x).

Location

Data [image] Build Data [image] Coord

See Also

Build Data, Coord, UnBuild Coord, UnBuild Data, Properties (Object), and Object Menu

See Examples

FutValue.vee


Build Data

A menu item.

Use

Use Build Data to access the following objects that create containers of particular data types from separate components:

Build Coord

Build Complex

Build PComplex

Build Waveform

Build Arb Waveform

Build Spectrum

Build Record

Location

Data [image] Build Data

See Also

Allocate Array, Build Arb Waveform, Build Complex, Build Coord, Build PComplex, Build Record, Build Spectrum, Build Waveform, Set Mappings, Set Values, and UnBuild Data.


Build PComplex

An object that creates a PComplex (polar complex) number from separate components.

Use

Use Build PComplex to create a PComplex number from the magnitude and phase components. Units of the phase component are determined by the Trig Mode setting under File [image] Default Preferences.

Notes

If one of the inputs is an array, the other input must be either a Scalar or an array of the same size and shape. Both inputs are converted to type Real64. The output is of the same shape as the inputs. The input values' mappings are ignored and the output PComplex value is not mapped.

The phase of the initial value is normalized to fall between pi and -pi radians. If the magnitude is negative, it is converted to positive and the phase angle is shifted 180 degrees.

Location

Data [image] Build Data [image] PComplex

See Also

Alloc PComplex, Build Complex, Build Data, Default Preferences, PComplex, UnBuild PComplex, Properties (Object), and Object Menu

See Examples

Complex.vee, FutValue.vee, and Manual10.vee


Build Record

An object that creates a record from separate components

Use

Use Build Record to create a record from scalar or array components. The input data components become fields in the output record. The output record can be either a scalar or a one-dimensional array.

Open View Parameters

Output Shape - You can set the shape of the output record to either Scalar or Array 1D.

Notes

The fields in the record are named from the names of the corresponding input terminals. The field names are case insensitive (lowercase and uppercase letters are equivalent). Field names may not be duplicated within a single record. Additional data inputs may be added to create a record with any number of fields. Records of records are allowed (where a field in a record is itself a record). There is no limit on recursion (except for the available memory).

If all inputs are scalar quantities, the record on the Record output pin will be a scalar record consisting of one field for each input, regardless of the specified Output Shape.

If one or more of the inputs are array, the shape of the resulting record depends on the specified Output Shape:

If Scalar is specified as the Output Shape, the output record will be a scalar that consists of one field for each input. Each field will be either a scalar or an array, the same shape as the corresponding input.

If Array 1D is specified as the Output Shape, the output record will be a one-dimensional array of records with fields for each input. If an input is a scalar or one-dimensional array, the corresponding field in the record will be a scalar. If an input is an n-dimensional array, the corresponding field will be an array of n-1 dimensions. If more than one of the inputs are arrays, they must all have the same size and shape. Here are some examples:

If input A is a one-dimensional array 10 elements long and input B is a scalar, the output will be a one-dimensional record array of 10 elements with two fields, A and B. The individual elements of the A input array will appear in the individual array elements of field A in the output record. Input B will be duplicated 10 times in the B field of the output record.

If an input is an array of two or more dimensions, the output record will still be an Array 1D. For example, if an input field is a two-dimensional array, 10-by-3 in size, the output record is a one-dimensional array with a length of 10, but with a field which is a one-dimensional array of 3 elements.

Location

Data [image] Build Data [image] Record

See Also

From DataSet, Get Field, Merge Record, Record Constant, Set Field, SubRecord, To DataSet, buildRecord(), Declare Variable, and UnBuild Record.

To Collect Data into a Record, Properties (Object), and Object Menu

See Examples

appA_Records1.vee and Ch5_UnBuild.vee


Build Spectrum

An object that creates a Spectrum from separate components.

Use

Use Build Spectrum to build spectrum values from an array of PComplex or Complex numbers and the frequency interval information.

Example

If you have an Array 1D of [5], PComplex (0,@1), (0,@2), and so forth, and frequency start equals 11 and stop equals 16, then frequency sample equals 11, 12, 13, 14, 15.

Open View Parameters

Start/Stop Freq |Center/Span Freq - Determines whether the two type-in values represent Start/Stop or Center/Span. Either Start/Stop or Center/Span values can be added as inputs.

Freq Sampling - Specifies whether the frequency sampling values are sampled linearly or logarithmically. Default is Linear.

Notes

The input PComplex values' mappings are ignored.

VEE does not track dB-scaled data. When you perform operations on dB-scaled data, you must ensure that they are done correctly.

To convert between linear- and db-scaled data, use the library programs provided with VEE in the lib directory under the VEE program installation directory.

There are the same number of points as sampling intervals. Each point is at the beginning of the sampling interval.

Location

Data [image] Build Data [image] Spectrum

See Also

Build Data, Build Waveform, and UnBuild Spectrum.

fft(x), Properties (Object), and Object Menu


Build Waveform

An object that creates a Waveform from separate components.

Use

Use Build Waveform to create a Waveform from a real array of amplitude values and time span information.

Open View Parameters

Time Span - The length of time in seconds over which the y data was sampled. Time Span may be added as a data input. Default is 20m seconds.

Notes

The input values' mappings are ignored. Build Waveform assumes the y data was sampled linearly at a constant rate over the given interval.

There are the same number of points as sampling intervals. Each point is at the beginning of the sampling interval.

Location

Data [image] Build Data [image] Waveform

See Also

Build Arb Waveform, Build Data, Build Spectrum, and UnBuild Waveform.

ifft(x), Properties (Object), and Object Menu

See Examples

DigFilt.vee and ReadMarkerValues.vee


Agilent I/O Monitor

I/O Monitor

IO Monitor is a utility that traces the I/O calls of targeted library layers. Although IO Monitor is specifically targeted for the .NET Framework, it will also work for legacy applications that use the targeted I/O library layers.

IO Monitor Information Flow

IO Monitor receives tracing/debugging information from I/O library layers and other software components. The individual pieces of information that sources generate are called (trace) events. Although the IO Monitor is the destination for tracing information, the flow of information is not always unidirectional. IO Monitor must be able to control its sources, for example turning tracing on and off or changing tracing parameters dynamically. Therefore, the flow of information between the IO Monitor and its sources is bidirectional and asynchronous.

The VISA and SICL trace points in the previous graphic are valid entry points to controlling your instrument. For VISA tracing to work, the Agilent VISA libraries are required. The SICL Detail Trace captures the lowest level interaction between the instrument driver and the instrument and is often the most useful of the traces.

IO Monitor Benefits

You can correlate higher level calls from sources like DirectIO and VISA-COM with the corresponding lower level API. "When I do this in DirectIO, what actually happens in the API?" You can see the instrument command sequences sent to a device by a specific device driver or high level I/O application. When you have problems with your programs, such as not getting the expected results or receiving errors from devices, you can trace your programs, log the trace to a file, and then send the file to the support team for help. If you have an I/O bottleneck, use IO Monitor to trace the calls to the API and to track where time is being spent.

Notes

Agilent IO Monitor is a general purpose bus monitor and can log messages that other programs input/output to the bus.

Location

I/O [image] I/O Monitor

See Also

Advanced I/O and Instrument Manager.

To Monitor Bus Messages


Button

See Toggle Control.


by Name

A function which manages the arrangement of icons (minimized windows) in the VEE workspace.

Use

Use by Name to lexicographically organize icons (minimized windows) in the VEE workspace. Icons will be aligned and/or stacked at the bottom of the workspace. The lexicographical organization is based on the name appearing in the title bar of the icon.

Location

Window [image] Arrange Icons [image] by Name

See Also

Arrange Icons, by Position and Minimize All.


by Position

A function which manages the arrangement of icons (minimized windows) in the VEE workspace.

Use

Use by Position to physically organize icons (minimized windows) in the VEE workspace. The icons will be neatly aligned and/or stacked at the bottom of the workspace.

Location

Window [image] Arrange Icons [image] by Position

See Also

Arrange Icons, by Name and Minimize All.


Call

An object that executes a previously defined function.

Use

Use Call to execute (call) a previously defined UserFunction, Remote Function, or Compiled Function. Each input and output on the Call Function object corresponds to the respective input/output on the called function. Call Function inputs are passed to the called function by position, not by name. For example, the Call Function object may have as its inputs, A and B. But the called function may have as its inputs x and y. No matter, the first input (A) on Call Function is passed as the first input (x) of the called function. Only position is significant.

You may also call a UserFunction, Compiled Function, or Remote Function by including its name in any expression whose evaluation is delayed until run time. These include expressions in various objects, such as Formula, If/Then/Else, and Set Values, and expressions in Sequencer and I/O transactions. For example, you can call the function someUsrFunc by including the expression 2+someUsrFunc(a) in a Formula object.

You can select a function to call in two ways. You can execute Select Function in the object menu and select a name from a list of available functions, or you can type in the name directly in the Function Name field. In either case, Call will automatically configure its input and output pins for the called function, if that function is recognized by VEE.

Since VEE can Call UserFunctions (either locally created or imported from a library), Compiled Functions, or Remote Functions, it is possible to have two functions with the same name. Naming conflicts in a Call object are resolved by searching tokens in the following order:

1. Function names found in the same library as the calling object

2. Local UserFunctions

3. Imported UserFunctions, Compiled Functions, and Remote Functions. The precedence between these three is not guaranteed. To ensure the desired selection, include the library name in the call, using “dot” notation. For example, myLib.func().

The search order described above applies to Execution Mode VEE 5 and higher. In earlier Execution Modes, function names were searched in a different order. This difference in search order can have a dramatic effect on programs containing similarly named functions from different libraries. For more details, refer to Execution Modes.

Open View Parameters

Function Name - The name of the UserFunction, Remote Function, or Compiled Function to be called.

Object Menu

Edit UserFunction - Displays the editing window to the named UserFunction. When you're done editing, press the close or minimize button in the upper right corner of the window.

Select Function - Lists the functions currently known to VEE. Imported and Remote UserFunctions and Compiled Functions are listed by library name. When you select a function, the input and output pins on this object are automatically configured as defined by the called function. (This selection is grayed out if there are no UserFunctions or Compiled Functions.)

Configure Pinout - Automatically configures the input and output pins on this object as defined by the called function. (This selection is grayed out if the named function currently doesn't exist in VEE.)

Notes

The Call Function object acts much like a math function call. Any inputs act like the formal arguments of an internal VEE function, while any outputs act like return values from that function.

VEE 4 and higher Execution Modes - If Execution Mode in Default Preferences is set to VEE 4 or higher, the execution of Call Function is asynchronous -- a call to a UserFunction will "time-slice" with parallel threads. If the UserFunction is executing and gets called again from another part of the program, the second call will block until the original call returns. Calls to Compiled Functions and Remote Functions are synchronous (see below).

VEE 3 - If Execution Mode in Default Preferences is set to VEE 3, the execution of Call Function is synchronous -- a call to a function will suspend the execution of parallel threads until the function is completed.

Location

Device [image] Call

See Also

Delete Library, Edit UserFunction, Formula, Import Library, UserFunction, UserObject, Properties (Object), and Object Menu

To Call a UserFunction in a Program


Call Stack

A View menu object that is useful for program debugging.

Use

Use the Call Stack tool window as an aid in debugging your VEE program. The Call Stack tool window displays the UserObject or UserFunction where the program is currently executing. In addition to identifying the currently executing object, the tool window also shows the list or hierarchy of which UserObject or UserFunction invoked or called the currently executing object.

The Call Stack tool window only displays useful information when the program is in a paused state. No information is available while the program is running. You can pause the program by any of several methods including Activate Breakpoint, Pause, etc.

Window Information

The Call Stack tool window contains no user-editable fields or buttons. When the program is paused and Call Stack is active, two things will occur.

1. The object that will be the next to execute is highlighted in the VEE workspace.

2. The hierarchy of calls that lead to the currently executing object or function is displayed inside the tool window. Clicking on any of the items listed in the hierarchy will bring that UserObject or UserFunction into the VEE workspace and highlight it.

Notes

Call Stack can be used in conjunction with the Step Into, Step Out and Step Over functions as an aid in debugging your VEE program.

Location

View [image] Call Stack

See Also

Activate Breakpoints, Find, Pause, Profiler, Run/Resume, Step Into, Step Out, Step Over, and Toggle Breakpoint

To View the Call Stack

Copyright (c) 1991-2007 Agilent Technologies, Inc.


Cascade

A function for managing windows in the VEE workspace.

Use

Use Cascade to arrange all opened (non-minimized) windows in the VEE workspace, as overlapping windows. Windows in the workspace will be stacked and offset down and to the right.

Notes

When multiple windows are open in the VEE workspace, it is possible to use the Ctrl key, in combination with other keys, to scroll through other non-minimized windows in the workspace.

Simultaneously pressing the Ctrl+Tab or Ctrl+F6 keys, moves the current top window to the bottom of the window stack. The next window down in the stack then becomes visible.

Simultaneously pressing the Ctrl+Shift+Tab or Ctrl+Shift+F6 keys moves the bottom window in the window stack to the top of the window stack.

Location

Window [image] Cascade

See Also

Arrange Icons, Close All, Minimize All, Tile Horizontally, and Tile Vertically.


Change Extension

Changes the file name extension. For example, using this object, you could change the file test.txt to test.doc.

Location

System [image] Path [image] Change Extension


Check Box

See Toggle Control.


Clean Up Lines

Redraws all lines in the Main program, UserObject, or UserFunction to route around objects using only horizontal and vertical line segments.

Use

If you disable Automatic Line Routing, connecting lines are straight from pin to pin (unless tacked). Select Clean Up Lines from time to time to tidy up the lines in your program.

Notes

Clean Up Lines is context sensitive; when it is selected from the UserObject or UserFunction Edit menu, only the lines within that particular context are affected. When selected from the menu bar Edit, only the lines in the root context (not in any UserObjects) are affected.

It may take several moments to completely re-route the lines in a complex program.

When a particular routing seems complex, move some of the objects apart to give the Auto Line Routing feature more room to find a shorter path.

After using Clean Up Lines, sometimes it is difficult to determine if two lines cross each other or if one line is connected to three places. Use Line Probe to display the endpoints of the lines.

Location

Edit [image] Clean Up Lines
or
UserObject (Object Menu) [image] Edit [image] Clean Up Lines

See Also

Default Preferences, Line Probe, and UserObject.


Clear All Breakpoints

Clears execution breakpoints.

Use

Use Clear All Breakpoints to delete all breakpoints from objects when you are finished debugging.

Location

Debug [image] Clear All Breakpoints

See Also

Activate Breakpoints, Properties (Object), and Toggle Breakpoint.

To Control Breakpoints


Clone (Object Menu)

Duplicates this object and places a copy of the object in the Paste buffer.

Use

Use Clone to create a copy of the object. Clone makes a duplicate object immediately available and puts a copy of the object in the Paste buffer. Clone copies all the attributes of the cloned object including terminals, parameters, and size.

Notes

To copy multiple objects at the same time, select the objects using CTRL-Left Button or Edit [image] Select All, then use Edit [image] Copy and Edit [image] Paste (or CTRL-c and CTRL-v).

Each Clone overwrites the previous content of the Paste buffer.

Each Clone of a UserObject is an independent copy of all objects in it. Changing one copy does not affect any others.

Each Clone of an Instrument Panel reflects a different state of the same instrument.

Short Cuts

Select object(s) to be cloned. Place the mouse over the object(s) and press and hold CTRL-Left Button. Drag the cloned object(s) to the desired location (you must move a distance of at least 65 pixels before the object(s) will be cloned).

Location

On each object menu [image] Clone

See Also

Object Menu, Cut (Object Menu), Copy, Paste, and Replace.


Close All

A function for managing windows in the VEE workspace.

Use

Close All will close all open or minimized windows (icons) and leave an empty VEE workspace.

Location

Window [image] Close All

See Also

Arrange Icons, Cascade, Minimize All, Tile Horizontally and Tile Vertically.


CLR Version

Retrieves the version of the Common Language Runtime (CLR) from the host machine.

Location

System [image] Environment [image] CLR Version


Collector

An object that collects data and outputs an array.

Use

Use Collector to create a one-dimensional array from scalar input data, or to create an output array from collected input arrays. If the input arrays have "n" dimensions, the collector can either output an array of n+1 dimensions, or it can output a one-dimensional array (with the input data "flattened"). When all data has been collected, activate the XEQ pin to output the resulting array.

Open View Parameters

Output Shape - Choose one of two selections:

n+1 Dim Array - The input signals (arrays of n dimensions) are collected and output as an array of n+1 dimensions.

1 Dim Array - The input signals, regardless of shape, are "flattened" by the collector and output as an Array 1D.

(For scalar input data, the output shape will be "Array 1D" regardless of the selection.)

Object Menu

Clear - Clears the contents of the Collector.

Notes

Because XEQ is required on the Collector you cannot add another XEQ pin or delete it.

The Collector continues to collect the input data until the XEQ pin is triggered.

The Collector has two inputs; one for the data coming in (any shape and type); the other tells the object when to execute. The Collector accepts multiple pieces of data on the first data input pin, and collects the data until the XEQ pin is activated. Then the object copies the full set of data to its output pin and propagates its output. The output data pin is never propagated until the XEQ pin is activated. Once the data propagates, the Collector clears its internal buffer and again starts collecting data. The type of the output signal is determined by the type of the first data container coming in after each XEQ or Clear. All subsequent containers are coerced to the type of the first one. If coercion fails, an error is reported.

The shape of the output signal depends on the Output Shape selection:

n+1 Dim Array operation - If you select n+1 Dim Array for the Output Shape, the Collector will collect the data coming into its Data pin, and will output an array of one dimension higher than the number of dimensions of the input data. Each input signal must be the same size and shape as the first input signal, until the XEQ pin is triggered. No mapping information is copied -- the output signal is not mapped.

For example, if the first input data is a Real64 1D array, 10 long, each subsequent input signal must be a 1D array, 10 long, of a type that can be coerced into Real64, until the XEQ pin is triggered. The output signal will be a Real64 2D array with 10 columns and n rows, where "n" is the number of times data was sent to the Data input pin before XEQ was triggered.

1 Dim Array operation - If you select 1 Dim Array for the Output Shape, the Collector collects the data coming into its Data pin and outputs an Array 1D, regardless of the shape of the input data. Scalar or Array 1D data is appended to the end; multi-dimensional arrays are flattened into an Array 1D and then appended.

For example, if the data in is a scalar Real64 value 1.2, then a scalar Int32 value 34, then XEQ is activated, it will output a Real64 Array 1D, two long, with the values [1.2, 34.0]. Then, if it is activated with several Complex data containers, it will output a Complex Array 1D.

Note that for scalar inputs of any type, the Collector generates the same output signal regardless of the Output Shape selection.

Since Waveform and Spectrum signals do not support more than one dimension, they are not allowed as inputs when the Collector is operating in the n+1 Dim Array mode. To collect Waveform or Spectrum data into a 2D array, unbuild the data first and then collect it into a 2D array. Note that the mapping information will be lost.

Since Record and Coord containers only support up to 1D arrays, only scalar Record or Coord containers are allowed as inputs when the Collector is operating in the n+1 Dim Array mode.

Enum inputs are converted to type Text before being placed into an array.

For Record inputs, the field names, types and sizes must match.

The Collector begins with its internal buffer cleared. It clears its internal buffer of collected data each time the XEQ pin is activated. You can add a control input for Clear and programmatically clear the Collector data before XEQ is activated. Subsequent activation of the data input starts the collecting over again. The output is not propagated until XEQ is activated.

If the XEQ pin is activated, and the data input has not been activated with non-nil data since the last clear, the Collector will output a nil signal in VEE 3 execution mode. If you are in VEE 4 or higher execution mode and the input data type is known, you will get a zero-element-array of that data type. If the input data type is not known, the Collector will output a zero-element-array of type Int32.

Location

Data [image] Collector

See Also

Allocate Array, Concatenator, Get Values, Set Values, Sliding Collector, Properties (Object), and Object Menu

To Collect Data into an Array


Color Alarm

An object that displays a different color and text string, depending on the value of the Scalar input.

Use

Use Color Alarm as an "LED" that displays a color and a text string, based on an input value and user-defined ranges. The input value may also be displayed in an optional digital numeric field.

Properties

ClearAtPreRun - When the property is True, the contents of the Color Alarm are cleared at PreRun. Default is True.

 ClearAtActivate - When the property is True, the contents of the Color Alarm are cleared at Activate. Default is True.

Shape - Selects the shape of the Color Alarm display. Default is Circular.

 Show 3-D Border - If the property is True, the Color Alarm is shaded to give it a 3-dimensional look. If the property is False, the Color Alarm is displayed as one flat color; this is useful when you need very small "LED" displays, you need the object to operate a little faster, or you don't like the 3-D look.

 ShowDigitalDisplay - If the property is True, a digital display of the input value is displayed at the bottom of the open view of the object. If the property is False, the digital display is not displayed and the object operates faster. Default is False.

HighColor - Specifies the color used for the highest range (i.e., greater than High Limit).

 High Text - Specifies the text displayed on the Color Alarm when the HighColor is used. Default is High.

 High Limit - Defines the numeric lower limit for the highest range. This value must be greater than or equal to the Low Limit.

 MidColor - Specifies the color used for the middle range (i.e., less than or equal to High Limit and greater than Low Limit).

 Mid Text - Specifies the text displayed on the Color Alarm when the MidColor is used. Default is Mid.

 Low Limit - Defines the numeric upper limit for the lowest range. This value must be less than or equal to the High Limit.

 LowColor - Specifies the color used for the lowest range (i.e., less than or equal to the Low Limit).

 Low Text - Specifies the text displayed on the Color Alarm when the LowColor is used. Default is Low.

Notes

The input data must be Scalar and able to be converted to Real64 (Complex, PComplex, Spectrum, and Coord must be first "unbuilt".)

The Low Limit must be less than the High Limit.

To use only 2 ranges of color, set the Low Limit equal to the High Limit.

To use only 1 color, set the LowColor, MidColor, and HighColor to the same color.

Location

Display [image] Indicator [image] Color Alarm

See Also

AlphaNumeric, Fill Bar, Logging AlphaNumeric, Meter, Tank, and Thermometer.

To Show a Color Alarm

Object Menu


COM Objects - Troubleshooting

On rare occasions, when using a COM type library as a .NET assembly in Microsoft Visual Studio .NET or Agilent VEE environments, you may receive caution messages.

Cause

Both Microsoft Visual Studio .NET and Agilent VEE try to automatically convert a COM type library to a .NET interop assembly using TypeLibConverter.ConvertTypeLibToAssembly API. You are seeing error messages because the API failed to convert the COM type library to a .NET interop assembly.

Workaround

To work around this problem, try to use the command line utility TlbImp that comes with .NET Framework SDK 1.1. You will need to download and install the SDK from the Microsoft Developer's Network because VEE does not distribute it. If you have Visual Studio .NET 2003 installed, then you already have the SDK installed and there is no need to download.

  1. Open a command window and change directory to an empty folder.

  2. Enter the following: <PathToSDK>\TlbImp.exe <PathToYourComTypeLib.dll>

For example, c:\program files\Microsoft Visual Studio .NET 2003\sdk\v1.1\bin\TlbImp.exe
c:\program files\IVI\bin\rsfs.dll

This will generate a .NET interop assembly, for example, Rsfs_RohdeAndSchwarzLib.dll in your clean folder. It will also generate any dependent assemblies in that same directory.

  3. Copy the generated assemblies to where your VEE program is. For example, if your program is in C:\VEE programs\Rsfs.vee, then copy all of the generated assemblies to c:\VEE programs.

  4. Open your VEE program and start using them as normal. For example, if it is an IVI-COM driver, you may follow the instruction in the "To/From IVI-COM" online help topic. If it is any other COM type library, you browse to the interop assemblies using the Device [image] .NET Assembly References dialog.

Notes

You may also use TlbImp to generate a Primary Interop Assembly, which can be shared by multiple programs without having to be copied to the same directory as the program. This is sometimes the best approach, for example, with IVI-COM drivers. Refer to the Microsoft Developer's Network for more information about TblImp.


Command Line

Retrieves the full command line, with parameters, that was used to launch this VEE session.

Location

System [image] Environment [image] Command Line


Command Line Args

Retrieves the command line arguments used to start the current session of VEE into a one dimensional array.

Location

System [image] Environment [image] Command Line Args


Comparator

An object that compares two values then outputs the coordinates where the comparison fails.

Use

Use the Comparator to compare a numeric test value, such as a Waveform or Coord, with a reference value. If one or more of the values in Test Value fails the comparison, a Coord Array 1D is output on the Failures output pin and the Failed output pin activates. If all values pass the comparison, an empty Coord is output on the Failures output pin and the Passed output pin activates.

The independent field (x) in the Failures output Coord Array 1D contains the index or mapping of each failure point. The dependent field (y) contains the Test Value that failed.

Open View Parameters

Test Value == Ref Value - Change the comparison operator by clicking on it and selecting the function from the list that is displayed. Default is ==.

Notes

The Comparator compares only numeric values, even if they are in Text objects. The Comparator cannot compare text strings.

The shape of the Ref Value is treated as the same shape as the Test Value. For example, a Scalar Ref Value of 3 is treated as an Array 1D (with all elements equal to 3) when the Test Value is an Array 1D. If arrays are compared, their size and number of dimensions must match.

If Test Value is a scalar, Ref Value must be a scalar.

If Test Value is an unmapped array, any mappings on Ref Value are ignored.

If Test Value is a mapped array, the independent variable of the Failures output Coord (x) is the mapping of the element that failed.

If Test Value is a Coord, only the dependent variable of the Coord is used in the comparison. The Failures output Coord contains the Coord value that failed.

All tests use an "almost equal" algorithm that checks equality or inequality to at least six significant digits. If the Ref Value is an array with more than one element, a value for "virtual zero" is derived from the reference data's magnitude. Any data points with a value of "0" must be matched with this "virtual zero" value.

Location

Device [image] Comparator

See Also

Allocate Array, Build Arb Waveform, Coord, If/Then/Else, Set Values, Properties (Object), and Object Menu


Complex

An object that outputs constant Complex scalars or an Array 1D.

Use

Use Complex to set a Complex Constant or to get user input. Click on the entry field to enter a value.

Example

To use Complex as a prompt on a panel, change the name of the Complex object to a prompt such as Enter the AC voltage:. The user fills in the requested information in the entry field.

Type in (2,10/27) to have the Complex constant evaluate the formula and display the answer.

Properties

 DataShape - Sets the initial data shape of the value(s) to be output with this object. Default is Scalar.

 ArraySize: - When 1D Array is selected, ArraySize sets the length of the array. Default is 10.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if 1D Array is selected.

 ShowArrayIndices - When the property is True, each line in the entry field is indexed. This selection is only available if 1D Array is selected. Default is True.

 Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

 InitialValue - Specifies the value to be set. Default value is (0, 0).

 InitializeAtPreRun - When the property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When the property is True, the InitialValue is set at Activate time. Default is False.

 NumberFormat: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Sat 01/Jan/2003 17:01:38). Default is Standard.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires a Complex value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Complex is configured to be an array.

You can enter just the real and imaginary values, separate them with a comma, and let VEE format the number for you.

Location

Data [image] Constant [image] Complex

See Also

Alloc Complex, Build Complex, Default Preferences, Constant, Coord, Date/Time, Selection Control, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real32, Real64, Text, Toggle Control, Boolean.

To Use a Data Constant and Object Menu


Complex Plane

An object that displays continuously-generated complex data as a Cartesian plot.

Use

Use Complex Plane to display Complex, PComplex, or Coord data values on a real versus imaginary axis.

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Imag - The name of the Y (imaginary) axis.

Trace1 - The name of the first trace.

Real - The name of the X (real) axis.

Object Menu

Auto Scale [image] - Clicking these menu items immediately re-scales the display to show the entire trace. (Can be added as control pins, or set using the Scales properties tab to automatically re-scale the display after data is collected.)

Auto Scale - Automatically scales both axes.

Auto Scale X - Automatically scales the X axis.

Auto Scale Y - Automatically scales the Y axis.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets the pen to display the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Y-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints or plots a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When the property is True, the display is cleared at PreRun time. Default is True.

 ClearAtActivate - When the property is True, the display is cleared at Activate (context entry) time. Default is True.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EditTracesAndScales to control the edit-button function of the trace legends. Default is True.

 ShowScalesLegend - In the open view, controls visibility of the scale names. Use EditTracesAndScales to control the edit-button function of the scale legends. Default is True.

 ShowScaleLabels - In the open view, controls visibility of the values labeling the scale axes. Default is True.

 ShowScrollBars - In the open view, controls visibility of the scroll bars on the X and Y scales. Default is True.

 ShowAutoScaleButton - In the open view, controls visibility of the Auto Scale Button. Default is False.

 EditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use ShowTracesLegend and ShowScalesLegend to control visibility of the trace(s) and scale(s) names.

GridType - Default is Axis.

NumMarkers: - Allows you to find the exact value of a data point on the displayed curve. If the data is plotted on a log scale, the values shown on the marker are the linear data points.

To move markers to a different trace, go to the open view and click on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

 MarkersInterpolate - When the property is True, you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

 MarkerColor - The color of the markers

DisplayBackColor - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view. The default Background color is set in Default Preferences on the Colors tab for Screen Element: Graph Background.

 ScaleLabelFont: - Allows you to select the font of the scale labels from the list of available fonts on your system. The default font for scale label text is set in Default Preferences on the Fonts tab for Screen Element: Graph Scale Label Text.

Traces Category:

Name - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Color - The color of the trace. Each added trace has a different color than the existing traces. Default for the first trace is yellow.

LineStyle - The format of the line connecting data points. Default is a continuous line.

PointStyle - The symbol that marks each data point. To show unconnected data points, select the single dot LineStyle format and the desired PointStyle symbol. Default is a dot.

Scale - If it exists for more than one Y scale, choose which scale this Trace is scaled by.

ScaleNumberFormat: (a property that appear for the X and Y scales, and for any additional Y scales.)

Scales Group:

Show Scale: - If you have multiple Y scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name: - The names of the scales appearing in the open view.

Automatic Scaling: - Controls whether the display automatically re-scales to show the entire trace immediately after it receives data. Default is True. If this is turned off, you can re-scale the display by using the Auto Scale button on the General tab, in the Layout group, or the Auto Scale command on the object menu.

Maximum: - The maximum values of the scales.

Minimum: - The minimum values of the scales.

Label Spacing: - Controls which tic marks are labeled with the scale values. Default for X scale is Every Other Tic; default for Y scale(s) is Every Major Tic.

Mapping: - The way the x and y data is mapped to the display. The mapping may be linear or log. To make a log-log plot, change both X and Y axes to Log. Default is Linear.

Log Cycles: - The maximum number of decades shown (counting down from the maximum x and y values) when Automatic Scaling is on. Log Cycles is only used when the Mapping is Log. Log Cycles is useful when a trace contains a large dynamic range in the data. Default is 4.

Scale Color - The color of any background grid or tic marks. Default is Gray.

Global Format - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Sat 01/Jan/2003 17:01:38). Default is Standard.

The X and Y marker values take on the same number format as the scale to which they are attached. The delta marker values for X and Y use the default number format unless you use the Time Stamp format. Then, if both markers 1 and 2 on the X scale, or both markers on the Y scale are using the Time Stamp format, the delta marker values use the Delta Time format.

Notes

Multiple traces is not supported for complex plane.

Inputs must be Scalar or Array 1D of type Complex, PComplex, or Coord.

Input data of type Coord is plotted by simply using its x and y values without first being converted to type Complex.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

When the AutomaticScaling property is True (Scales category), the program executes faster if a complete set of data is sent to the display. Then, the display automatically re-scales once. If a program sends one data point at a time to the display, the display may automatically re-scale after each data point, which will slow down program execution. In this case, use a Collector object to create an array, then send the array to the display.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A Text field named Scale with a value X, Y (or Y1), Y2, or Y3. The Scale field is required. An error occurs if it is omitted.

One or more of the following fields:

Name - Changes the scale name in the open view. Must be a text value.

Min - Sets the X scale minimum. Must be an integer or real value.

Max - Sets the X scale maximum. Must be an integer or real value.

Mapping - Must have a text value of Linear or Log.

AutoScale - Controls automatic scaling. Must have a text value of On or Off.

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties window. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers category. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display’s Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the display's Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] Complex Plane

See Also

Magnitude Spectrum, Polar Plot, Strip Chart, Waveform (Time), X vs Y Plot, XY Trace, Default Preferences, To Set Markers in the Display, To Get and Set Marker Properties, andObject Menu.


Component Driver

An instrument control object that reads and writes values to components you specifically select. No control panel is displayed for the instrument, which differs from the Panel Driver object.

Use

Use a Component Driver to control an instrument by setting the values of only a few components at a time. Before you can use a Component Driver, the instrument driver for the desired instrument must be installed.

To add a Component Driver object to the VEE work area, click on I/O [image] Instrument Manager... to display the Instrument Manager dialog box. Check the list of configured instruments to see if there is an entry for the instrument you want to use:

If the instrument you want is in the list, and is properly configured:

1. Click once on the instrument entry to highlight it.

2. Click on the Component Driver button.

If the instrument you want is in the list, but you need to change its configuration, click on Properties…, change the configuration using the dialog boxes, save the configuration (click OK), and then follow steps 1 and 2 above.

If the instrument you want is not in the list, click on Add…, configure the instrument using the dialog boxes, save the configuration (click OK), and then follow steps 1 and 2 above.

For information about the configuration dialog boxes, refer to Instrument Manager and Instrument Properties.

Notes

Component Drivers may be operated with Live Mode off. This allows you to run your program without communicating with the instrument, whether or not the instrument is connected to the computer. You must set Live Mode to on (refer to Instrument Properties) before your program will communicate with the physical instrument.

To be useful, at least one input or one output must be added to the Component Driver object. More than one input or output can be added and both inputs and outputs may appear on the same object. An input performs the set actions for the component. An output performs the get actions. Control pins are available as inputs to initialize the component, programmatically change the device address, and set the timeout value.

Location

I/O [image] Instrument Manager...

See Also

Direct I/O, Instrument Manager, Instrument Properties, Panel Driver, Add Terminal, Properties (Object)

To Use a Component Driver Object, Introduction to Panel Drivers and Component Drivers


Concatenator

An object that outputs the concatenation of all its input data into an Array 1D.

Use

Use Concatenator to combine two or more data elements into the elements of an Array 1D. The size of the resultant array is the sum of the sizes of the inputs. Data inputs can be added to allow three or more containers to be concatenated.

Enum inputs are converted to type Text before concatenation occurs.

Notes

The output data type is the highest type of all the input data types. If any input is an array of more than one dimension, the array is flattened (row major) into an Array 1D for the concatenation.

To concatenate multiple lines of Text into one line, use Accumulator.

Nil inputs are ignored. This is different than the concat(x,y) function which operates within the formula box. In the formula box, all nil inputs are automatically converted to Real64 scalars with value 0. Thus, concat(a,b), where a is nil and b is an Int32 scalar value 5, results in the Array 1D, two long of Real64 with values [0, 5]. The Concatenator object with two inputs with nil and an Int32 scalar value 5 outputs an Int32 array one long with value [5].

If the first value (first data input) is mapped, the other input values may be either mapped with the same point spacing, or unmapped. The result will be mapped from the Xmin to Xmin + dx * N where "Xmin" is the minimum value of the mapping of the first array value, "dx" is the distance between two consecutive points in the first value, and "N" is the size of the result array.

Location

Data [image] Concatenator

See Also

Accumulator, Allocate Array, Collector, Set Values, Sliding Collector, Properties (Object), and Object Menu

concat(x,y)


Conditional

A menu item.

Use

Use Conditional to access the following conditional branches:

If A == B

If A ~= B

If A != B

If A < B

If A > B

If A <= B

If A >= B

Use Conditional objects to decide which subthread to run.

Notes

Note the difference between Comparison items under Device [image] Functions & Object Browser and Conditional items. Comparisons are formulas with output 0 or 1; Conditionals are If/Then/Else and have two or more outputs, of which one fires.

Note that the return value of Logical items AND, OR, XOR, and NOT in the Device [image] Function & Object Browser... is of type Int32 and is the same shape as the operands. This is different than the conditionals such as == that always return a scalar.

The logical operators are defined for type text only in the sense of whether the string is null or not. That is, "0" and "1" are logically true since they are non-null strings, while "" is false. Therefore, "zoo" AND "" (null string) is logically false since the second string is null. Remember that when comparing a Text type to a non-string type, the latter is promoted to a Text type. This means that "zoo" AND "0" is true since the real 0 is promoted to the string "0" and, since both strings are non-null, the AND expression is true, returning 1.

Location

Flow [image] Conditional

Then select the desired conditional branching object.

See Also

If A ~= B, If A == B, If A != B, If A < B, If A > B, If A <= B, If A >= B, and If/Then/Else.

Comparison, Triadic Operator, and Function & Object Browser.

To Branch within a VEE Program


Confirm (OK)

See OK.


Constant

A menu item.

Use

Use Constant to access the following input constants whose shape can be either scalar or array:

Boolean

Text

UInt8

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Complex

PComplex

Date/Time

Record

Notes

All Constant objects, except Text, support the use of arbitrary formulas in the input box. (Global variables are allowed only if they have been set in a previous execution of the program. Click on Globals in the Program Explorer to see what variables exist.) The formula is parsed and evaluated immediately after it is typed and entered into the edit field. The resulting Scalar number is used as the value for the Constant. Constants do not support input variables like the Formula object does, therefore you cannot use input variable names in the formulas. The typed in formula must evaluate to a Scalar value of the proper type or of a type that can be converted to the Constant you are using.

The syntax supported is the same as in the Formula object, but with some exceptions. You cannot use array building syntax ([, ]) operators to construct an array, since they would return a non-Scalar and the return value must be Scalar. Also, you cannot use input name variables in Constant objects.

In general, the use of any of the dyadic operators, parentheses for nesting, function calls, and the predefined numeric constant PI (3.1416...) is allowed.

The Variant type does not appear in the Constant object. The only way to create a Variant data type is use Declare Variable and select type "Variant."

Examples

When you type (2, @PI/2) into a PComplex object, it is evaluated and returns (2, @90) (if Trig Mode is set to Degrees).

When you type 14 + exp10(3) into a Real64 object, it is evaluated and returns 1014.

When you type (1, 2) into a Real64 object, an error is returned because VEE does not allow the conversion from Complex to Real64.

Location

Data [image] Constant

See Also

Complex, Coord, Date/Time, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real32, Real64, Record Constant, Selection Control, Text, Toggle Control, Boolean.

To Create a Record Constant

To Create an Array Constant

To Use a Data Constant


Continuous

A menu item.

Use

Use Continuous to access the following objects:

Int32 Slider

Int64 Slider

Real64 Slider

Int32 Knob

Int64 Knob

Real64 Knob

Location

Data [image] Continuous

See Also

Int32 Knob, Int32 Slider, Real64 Knob, and Real64 Slider.

To Use a Data Slider and Knob


Control Input (Object Menu)

Adds an asynchronous control input terminal to the object.

Use

Use Control Input to add asynchronous inputs, such as Reset or Clear, to objects.

After selecting Control Input, choose the control to add from a dialog box. On some systems, the terminal for a control input is a different color than for a data input.

Notes

Control inputs are not available on all objects.

Activation of a control input pin does not cause the object to operate, it only forces that particular action to happen (for example, Clear).

Often the actions performed by a control input may also be done from a selection on the object menu or by a button on the open view.

Location

On each object menu [image] Add Terminal [image] Control Input

See Also

Add Terminal, Data Output (Object Menu), Delete Terminal, and Object Menu.


Coord

An object that outputs a constant Coord Scalar or Array 1D.

Use

Use Coord to set a Coord constant or to get user input. Click on the entry field to enter a value.

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are Scalar and Array 1D. Default is Scalar.

 ArraySize: - When Datashape 1 D Array is selected, ArraySize sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if Datashape 1 D Array is selected.

 ShowArrayIndices - When the property is True, each line in the entry field is indexed. This selection is only available if Datashape 1 D Array is selected. Default is True.

 Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is (0, 0).

 InitializeAtPreRun - When the property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When the property is True, the InitialValue is set at Activate time. Default is False.

Number Format - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Sat 01/Jan/2003 17:01:38). Default is Standard.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires a Coord value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Coord is configured to be an array.

Coords can contain more than two fields. For example, a Coord with three fields is (x, y, z).

The mathematic operations on Coords operate on the dependent variable only, that is, they operate on the y value of the (x, y) pair.

Example

Type in 2, 5 + exp10(2) to generate the Coord constant (2,105).

The Coord Array 1D can be used to define bounding envelopes on waveforms and as input to Comparators for waveforms. Use an Array 1D of Coords to define the limiting points on the bounding waveform. The limiting points are the endpoints of line segments that define the limiting waveform shape. Then send this array through the Build Arb Waveform box to create a limiting waveform. The new bounding waveform can be used in the Comparator box as one of the inputs to generate the points that fall outside the bounding waveform.

You can use the bounding waveform in the clipUpper or clipLower function to clip the waveform to the bounding limits.

To use Coord as a prompt on a panel, change its title to a prompt such as "Enter the Coordinates". The user fills in the requested information in the entry field.

Location

Data [image] Constant [image] Coord

See Also

Complex, Constant, Date/Time, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real32, Real64, Selection Control, Text, Toggle Control, Boolean, and To Use a Data Constant.


Copy

Places a copy of the selected objects in the Paste buffer, and on the Clipboard in Windows 2K and XP.

Use

Use Copy and then Paste to make multiple copies of a set of selected objects.

Notes

Copy is only available after objects are selected.

Each Copy overwrites the previous contents of the Paste buffer.

Copied objects can be pasted into another location in the same program, or into another VEE session. In Windows 2K and XP, copied objects can be pasted into other applications.

To copy a single object, use the Clone selection from its object menu. Copy is different from Clone in that Clone gives you a duplicate set of objects immediately and Copy only places the objects in the Paste buffer for later use.

Location

Edit [image] Copy

See Also

Clone (Object Menu), Cut, Object Menu, Paste, Replace, and Select All.


Counter

An object that displays and outputs the number of times its data input pin has been activated.

Use

Use Counter to keep a running count. Counter keeps a running count of the number of times an input has been activated by a previous object's output. The Counter output is a Real64 scalar.

Object Menu

Clear - Clears the contents of the Counter.

Notes

The data input for Counter does not require any particular type data and even counts an input with a nil value. It can also be cleared by activating the input Clear control pin.

The value of the Counter, a Real64 scalar, is available at the Counter output.

Location

Device [image] Counter

See Also

Accumulator, Properties (Object), and Object Menu


Create Directory

Creates a new directory.

Location

System [image] Directory [image] Create Directory


Create RunTime Version

Saves a secured version of the program that cannot be edited.

Use

Use Create RunTime Version to lock the main panel view of a program after it is completed and before users have access to it. Access to the detail view in a secured item is no longer available.

When you use Create RunTime Version, you are prompted for a file name to call the secured version. The secured file will then be saved with the name <filename>.vxe. To run a secured file, select File [image] Open... and change the Files of type: selection to Secure VEE Programs (*.vxe) and select the file. Many of the VEE development tools (Edit, Debug, ...) are not available when a secured file is loaded.

Notes

A secured program loads and runs faster than an unsecured program.

Use Default Preferences to set the file format for secured programs to ASCII or binary. The binary format, the default setting, saves files that are smaller in size and will load faster.

For added security, VEE cannot merge .vxe files into another program. However, VEE will import libraries saved as .vxe files.

Location

File [image] Create RunTime Version...

See Also

Default Preferences, UserFunction, UserObject.

To Secure a Program


Create UserObject

Puts selected objects into a UserObject.

Use

Use Create UserObject to group objects together logically and physically. Select the objects to be included and then select Create UserObject. The UserObject created contains the selected objects.

A UserObject operates just like any other object; no objects operate inside a UserObject until all data inputs to the UserObject are activated. All operations inside the UserObject must be complete before the data output is activated.

The maximize button on the right side of the title bar of the open view increases the size of the UserObject to the size of the VEE work area.

If the objects in the UserObject were connected to other objects before they were in the UserObject, terminals are automatically created on the UserObject to maintain the connections. Objects inside the UserObject can not be connected to objects outside the UserObject, without first adding input and output pins from the UserObject menu.

Notes

If no objects are selected, Create UserObject is not available. To create an empty UserObject, select UserObject from the Device menu. You can place new objects inside the UserObject after it has been created by moving them inside the UserObject window. Placing existing objects inside a new UserObject must be done with Cut and Paste.

It is convenient to save UserObjects of common functions (using Save Objects...) to create a library of functions to be used again.

When you Step Over a UserObject the entire context of the UserObject runs. Use Step Into to run individual objects within the UserObject and Step Out to run all remaining objects and exit the UserObject.

Location

Edit [image] Create UserObject

See Also

Add To Panel, Default Preferences, Create RunTime Version, Select All, Step Into, Step Over, Step Out, Unpack (Object Menu), UserFunction, and UserObject.

To Create and Use a Library of UserObjects

To Create a UserObject from Objects in a Program

To Create a UserObject in a Program


Create UserFunction

An Edit menu selection that allows you to create a UserFunction from user-selected VEE objects.

Use

By using Create UserFunction, you can collect a number of functionally related VEE objects together into a separate UserFunction. Converting related VEE objects into a UserFunction can be especially useful when those same objects are used repeatedly in your VEE program.

To create a UserFunction, select the VEE objects you wish to include in the function by holding down the CTRL key, and simultaneously clicking on the objects using the left mouse button. The selected objects will be highlighted with shadows.

After you have selected the objects you want to include in the function, then select Create UserFunction from the Edit menu. The Create UserFunction dialog box will appear. The Function Name: field in this dialog box will allow you to enter your own descriptive name for the UserFunction you are about to create. If you choose not to enter a new UserFunction name, the name will default to UserFunction1. Once you have selected a name for the new UserFunction, click on the OK button on the Create UserFunction dialog box.

After you have created the new UserFunction, all of the objects you selected will now appear in a new UserFunction window. The new window will have a title bar containing the UserFunction name you assigned. Additionally, a Call to this new UserFunction will appear as a Call object in the VEE window where the new UserFunction was created.

Notes

If no VEE objects have been selected in the window that is currently active, the Create UserFunction menu selection will be grayed out (unselectable).

Location

Edit [image] Create UserFunction

See Also

Call, Edit UserFunction, Import Library, UserFunction, and UserObject.

To Create a UserFunction from Objects in a Program

To Create a UserFunction in a Program


Cut

Deletes the selected objects and places them in the Paste buffer, and on the Clipboard in Windows.

Use

Use Cut to delete a set of selected objects or to remove the objects from one place on the work area and put multiple copies of them in another place on the work area (using Paste).

Notes

Cut is only available after objects are selected.

Cut is not available when a program is running.

To delete a single object, use the Delete feature from its object menu.

Each Cut overwrites the previous contents of the Paste buffer.

If you accidentally Cut objects, they can be recovered by using Undo.

Cut objects can be pasted into another location in the same program, into another VEE session, or into other applications.

To make multiple copies without deleting objects, use Clone or Copy. To cut objects without modifying the clipboard, use the object context menu Delete.

Cuts can be undone on both Panel and Detail views.

Location

Edit [image] Cut

See Also

Clone (Object Menu), Cut (Object Menu), Copy, Paste, Replace, To Undo an Operation, Delete (Object Menu), and Select All.


Cut (Object Menu)

Deletes the object and places it in the Paste buffer, and on the Clipboard.

Use

Use Cut to remove this object from your work area.

Notes

Cut is only available from UserObjects and UserFunctions.

Each Cut overwrites the previous contents of the Paste buffer.

Cut (Object Menu) is not available when a program is running.

If you accidentally Cut an object, it can be recovered by using Paste or Undo.

A cut object can be pasted into another location in the same program, or into another VEE session. A cut object can be pasted into other applications.

If you want to delete multiple objects, use the Cut selection from the Edit menu or draw a rectangle around the items you want to cut by holding down the CTRL key and moving the left mouse key. Right click on any open area in the work area and choose Cut from the menu.

Short Cuts

To delete the object under a pointer, press CTRL+D.

Location

On the object menu [image] Cut

See Also

Clone (Object Menu), Copy, Cut, Paste, Replace, and Select All.


Cyclic Button

See Selection Control.


Data Input (Object Menu)

Adds a data input terminal to the object.

Use

Use Data Input to increase the number of data input terminals the object uses. On some objects additional data inputs are automatically named A, B, C, and so on. You can change the names of most terminals to names that are more meaningful to you.

Although you cannot change the data type or shape of most input terminals, you can change these constraints on some objects, such as If/Then, Formula, Shift Register, and objects under the I/O menu.

Note
You should not change the data type or shape of an input terminal unless the object needs only that data type; if a constraint is changed from Any, the input data must be converted to the terminal constraint before the object processes the data. Conversions are time-consuming. If the conversion is unsuccessful, the object returns an error.

Notes

Data Input is only available from objects that permit additional data inputs.

Short Cuts

You can quickly add a data input terminal by placing the cursor over the input terminal display area and then pressing CTRL+A. Each press of CTRL+A inserts another data input terminal at the cursor location. The Add Terminal [image] Data Input adds the terminal at the end. CTRL+D deletes terminals covered by the cursor.

Location

On each object menu [image] Add Terminal [image] Data Input...

See Also

Add Terminal, Data Output (Object Menu), Control Input (Object Menu), Conditional, Delete Terminal, Object Menu, and Properties (Object).


Data Output (Object Menu)

Adds a data output terminal to the object.

Use

Use Data Output to increase the number of data output terminals. On some objects, additional data outputs are automatically named X, Y, Z, W, V and so on. You can change these data output names to names that are more meaningful to you.

The output terminal container information (data type and shape) is not displayed in the terminal information dialog box until after that object has executed.

Notes

Data Output is only available from objects that permit additional data outputs.

Short Cuts

You can quickly add a data output terminal by placing the cursor over the output terminal display area and then pressing CTRL+A. Each press of CTRL+A inserts another data output terminal at the cursor location. The Add Terminal [image] Data Output adds the terminal at the end. CTRL+D deletes terminals covered by the cursor.

Location

On each object menu [image] Add Terminal [image] Data Output...

See Also

Add Terminal, Data Input (Object Menu), Delete Terminal, Error Output (Object Menu), Instrument Manager, and Object Menu.


Date/Time

An object that outputs a constant date and time value. Date/Time takes an input date and time and converts it to the number of seconds between the input and the beginning of the Epoch (defined as beginning at 0000 hours UTC January 1, 0001 AD).

Use

Use Date/Time to display the time and date at the moment an object or data is created.

Date/Time can be used to calculate elapsed time between a past and current event by comparing the two mathematically.

To change a value such as the day, date, or time, type the value. For example, typing Tue changes Mon 27/Oct/2003 15:43:33 to Tue 28/Oct/2003 15:43:33. If you don't specify a value, the current day, date, or time is displayed. If you change just one of these the other time elements will stay the same.

Example

You can use Date/Time to determine the length of time that has passed between the moment a specific piece of experimental data was produced and another moment in time, either past or present. Use a Date/Time box to enter the new, arbitrary date then take the difference between the original, experimental data and the new arbitrary date.

To determine the length of time it takes for all or part of your program to execute, use Timer or now().

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object. Default is Scalar.

 ArraySize: - When 1D Array is selected, ArraySize sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if 1D Array is selected.

 ShowArrayIndices - When the property is True, each line in the entry field is indexed. This selection is only available if 1D Array is selected. Default is True.

 PasswordMasking - When this property is True, the input text is echoed as asterisks (*). This feature is useful when the operator is entering sensitive date/time data. The string that is output on the Date/Time output pin is not masked. Masking is disabled when Configuration is 1D Array. Default is False.

Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is Sat 01/Jan/1 17:00:00 MST.

 InitializeAtPreRun - When the property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When the property is True, the InitialValue is set at Activate time. Default is False.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). The Constant is reconfigured to match the shape of the incoming data. The control input should be a valid Date/Time string as given by the parse rules for date/time constants. These are the same rules as those for Direct I/O.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Date/Time is configured to be an array.

You can display Date/Time output in AlphaNumeric or Logging AlphaNumeric by using the Time Stamp number format available in those objects' Properties window.

You can write the Date/Time output to various locations such as a string, file, or printer by using objects such as To String, To File, or To Printer (I/O [image] To [image]). In these objects, use the Time Stamp format in a WRITE TEXT transaction.

For MS Windows, you can change the time zone that appears in this object by using the Date/Time Properties dialog box (Time Zone tab) in Control Panel. After changing the time zone setting, you must restart VEE for the change to take effect.

Location

Data [image] Constant [image] Date/Time

See Also

Timer

To Use a Data Constant


Date/Time Compare

Compares two dates/times.

Location

System [image] DateTime [image] Compare


Date/Time to Local Time

Converts a date/time value to local time.

Location

System [image] DateTime [image] To Local Time


Date/Time to String

Converts a date/time value to a string.

Location

System [image] DateTime [image] To String


Date/Time to Universal Time

Converts the system date/time to Universal Time.

Location

System [image] DateTime [image] To Universal Time


Day of the Week

Retrieves the day of the week from the given date.

Location

System [image] DateTime [image] Day of the Week


Day of the Year

Retrieves the day of the year from the given date.

Location

System [image] DateTime [image] Day of the Year


Declare Variable

An object that allows you to declare programming variables.

Use

Use the Declare Variable object to declare variables anywhere in a VEE program. Three types of variables can be declared:

Global - the declared variable can be used anywhere within the program. This is the default declared variable scope.

Local to Context - the declared variable is specific to the context in which it was declared, such as within a particular UserObject or a UserFunction.

Local to Library - the declared variable is specific to a particular Library and only its UserFunctions can get to it.

Object Menu

Add Field -- Adds a new field to the record at the end of the field list. A dialog box will allow you to define the name, type, and shape of the new field. This field is grayed out unless you choose the Record type.

Insert Field -- Inserts a new field to the record at a specified position. A dialog box allows you to define the name, type, and dimension of the new field. A second dialog box allows you to specify the insertion point if more than one field exists. This field is grayed out unless you choose the Record type.

Delete Field -- Allows you to delete record fields. A dialog box will list the available fields to delete. This selection is available only if the record has more than one field. This field is grayed out unless you choose the Record type.

Edit Event Handler -- Opens the Edit Event Handler dialog box if any event handler UserFunctions have been created for the declared ActiveX object.

 Create Event Handler - Opens the Create Event Handler UserFunction browser. This browser lets you create a UserFunction to handle an event generated by an ActiveX automation object. You can create an event handler for each event listed in the browser’s Member area. This menu pick is available when Type is set to Object and you have enabled events for the specified Library and Class.

 Generate

Record Constant -- Allows you to generate a Record Constant object whose fields match this Record configuration. This selection is available only if the type of the declared variable is Record.

Build Record -- Allows you to generate a Build Record object whose inputs match this Record configuration. This selection is available only if the type of the declared variable is Record.

Unbuild Record -- Allows you to generate an Unbuild Record object whose outputs match this Record configuration. This selection is available only if the type of the declared variable is Record.

Open View Parameters

Name: - The user-defined variable name. The default name is global1.

Scope: - The program scope of the declared variable. Valid program scope values are Global, Local to Context and Local to Library. The default program scope is Global.

Type: - The data type of the variable, such as Real64, Int32, Enum, etc. The default type is Real64.

When Type is set to Record, the Declare Variable dialog box expands to the right. The expanded area lets you define and build the Record. Use Add Field, Insert Field, and Delete Field in the object menu to build the Record.

When Type is set to Object, a new field, "Sub Type", appears and the Declare Variable dialog box expands to the right. The expanded area lets you specify optional details when declaring a variable for an ActiveX or .NET object. You do not need to specify these details when declaring a variable; however, by doing so VEE will do type checking automatically to assure that the specifications are assigned only to the declared variable. For an ActiveX object to change values for Library, Class, and Events, click on EditE/font> Change the values in the resulting dialog box Specify Object Type. For a .NET object to change values for Assembly, Namespace, Type, and Members, set the Sub Type to .NET, then click Edit... Change the values in the resulting dialog box (Specify Object Type). Sub-Type "Any" allows an object of sub-type .NET, ActiveX(COM), or a VEE object such as an XYDisplay.

When Type is set to Variant, the value assigned to the variable can be any data type.

Num Dims: - The number of dimensions of the variable. The valid range is 0 through 10. The default value is 0.

Notes

For more information about programming techniques that effect the cleanup of ActiveX references, see the CreateObject topic.

Location

Data [image] Variable [image] Declare Variable

See Also

ActiveX Automation References, ActiveX Control References, Delete Variable, Get Variable, Set Variable, Specify Object Type, Variant, Properties (Object), and Object Menu

To Create a Variable and Releasing ActiveX References

See Help => Contents and Index => Tell Me About... => Active X for details about using ActiveX objects and controls in VEE.


Default Preferences

A menu choice that provides you with a dialog box for setting the default preferences in your VEE programming environment.

Use

Use Default Preferences to set VEE work area options. Saved options are used when you start up VEE and when you select New. Some of these options are also saved in your program, so you can configure each program with a different set of defaults.

Dialog Information

General tab:

Environment group

Auto Line Routing- When the Auto Line Routing check box is selected, the lines connected to an object are automatically rerouted when that object is moved or sized. VEE draws only horizontal and vertical lines with lines routed around other objects. It may take several moments to redraw the lines for a complicated program. When the Auto Line Routing check box is not selected, connecting lines are drawn straight from pin to pin (unless tacked). Choose Edit [image] Clean Up Lines to reroute lines around objects.

Delete Variables at PreRun - When the Delete Variables at PreRun check box is selected, the values stored in all variables are deleted before the program runs each time. Because Get Variable objects cannot execute until the variables they call are set with Set Variable objects, an error will be returned if a required variable has not been set. When the Delete Variables at PreRun check box is not selected, the values stored in variables will not be deleted at PreRun, and the program runs using data from a previous run. However, you need to be careful, this data may be invalid (not correct for the execution of the program this time), no error will be reported, and you may encounter unexpected results.

Uncertain Data Flow Compiler Warning - When the Uncertain Data Flow Compiler Warning check box is checked, Uncertain Data Flow Compiler Warnings will be displayed in the Output window. Otherwise, VEE only logs Warnings and Errors in the Output window.

Code Completion and Insight- When the Code Completion and Insight check box is selected, Code Completion and Insight feature is enabled. All available choices will be prompted while you are typing in a formula box. By default, this item is checked.

Code Completion Supports Build-in Functions - When the Code Completion Supports Build-in Functions check box is selected, VEE Build-in functions will appear in the Code Completion window. Code Completion will not display any Build-in functions if this item unchecked.By default, this item is checked.

Code Completion Supports COM Constants- When the Code Completion Supports COM Constants check box is selected, COM Constants will appear in the Code Completion window. Code Completion will not display any COM Constants if this item is unchecked. By default, this item is unchecked.

Match Brackets in Formula- When the Match Brackets in Formula check box is selected, VEE will automatically mark matched brackets in grey in a formula. This feature is useful for complex formulas.

Execution Mode group:
For more information, see Understanding Execution Mode. For details about compatibility issues between execution modes, see Execution Modes.

VEE 8.5 - Runs the program using the same settings as the VEE 8.5 product. VEE 8.5 mode includes all the features of VEE 8 mode plus new Data Types UInt16.

VEE 8 - Runs the program using the same settings as the VEE 8.0 product. VEE 8 mode includes all the features of VEE 6&7 mode plus new Data Types Int32 and Boolean.

VEE 6&7 - Runs the program using the same settings as the VEE 6.0 product. VEE 6 mode includes all the features of VEE 5 mode plus new Data Types UInt8, Int16, Real32, and Variant.

VEE 5 - Runs the program using the same settings as the VEE 5.0 product. This allows programs written with VEE 5.0 to run exactly the same as they would under that older version. VEE 5 mode includes all the features of VEE 4 mode plus ActiveX support on Windows. NOTE: Some programs written with VEE 4.0 and older may behave differently in the VEE 5 mode.

VEE 4 - Runs the program using the same settings as the VEE 4.0 product. This programs written with VEE 4.0 to run exactly the same as they would under that older version. VEE 4 mode adds the compiler technology, which allows for the faster program run-time than older versions. NOTE: Some programs written with VEE 3.2 and older versions will behave differently in this mode. Even though the program may appear to run normally, errors may occur due to time-slicing differences.

VEE 3 (Not Compiled) - Runs the program with the older VEE interpreter to allow programs written with VEE 3.2 and older versions to run exactly the same as they would under that older version.

Trig Mode group:

Degrees | Radians | Gradians - specifies the default for trigonometric units used throughout this program. If you select Radians, your trigonometric calculations will execute the fastest.

Debug group:

Data Flow Rate: - Sets the rate at which the Data Flow markers move, indicating data flow through the program. Select a rate from 1 to 10 (where 10 is the fastest). The default rate is 6.

Disable Debug Features - Allows you to turn off all debugging features for the fastest possible program execution.

Check Instrument Addresses at PreRun - With instrument checking enabled, VEE checks all supported instruments at prerun to verify that the referenced instruments are accessible (live). If an instrument or interface is not accessible, VEE:

1. Shows a dialog box prompting the user to retry after fixing the problem. The user can answer "Yes" to retry the detection for this instrument, "No" to check the next instrument, or "Cancel" to completely bypass this instrument.

2. If that instrument is detected after retry, then VEE checks the next instrument.

3. After an unsuccessful retry (or a "No" answer), VEE shows a list of live instruments on the same interface type. Then the user can choose an alternate address for the current instrument.

Program Development group:

Alignment Spacing - Designates the amount of space (in pixels) that is placed between VEE objects when Edit [image] Align [image] Space Equally is checked. Choosing one of the other Align [image] commands causes the objects to align with the amount of space specified.

Binary RunTime File Format - Controls file format when saving a program as a .vxe file using File [image] Create RunTime Version. Turn on Binary RunTime File Format (the default) for smaller file size and better program security. When turned off, the file is saved in ASCII format.

Show Description Indicators - When checked, shows a small red triangle in the upper right corner of an object if there is a description for the object. You can click on the red triangle to initiate an description editing session.

Colors tab:

Screen Element - Allows you to select the screen element (a graphical part of VEE) for which you'll set the default color. You can change the color of some of these elements locally using the Properties selection on a specific VEE object's menu.

Color Value - Allows you to select the color of the screen element from a palette.

Enable Color Coding - When the Enable Color Coding is checked, the color coding is enabled. VEE will color the title bar of detail view objects and the background color of icon view objects using the current color coding theme. To change the color coding theme, please refer to To Change Color Coding Pattern. When this item is unchecked, VEE will use the Classic Blue Theme to color all screen elements.

Change Color Coding... - Opens the Change Color Coding Theme dialog box and allows you to change the color coding theme.

Import Color Coding... - Allows you to import a saved color coding theme from a XML file.

Export Color Coding...- Allows you to export the currently used color coding theme to a XML file.

Fonts tab:

Screen Element - Allows you to select the screen element (a graphical part of VEE) for which you will set the default font. You can change the font of some of these elements locally by using the Properties selection on a specific VEE object's menu.

Font Value - Allows you to select the text font of the screen element from the list of available fonts on your system.

Number tab:

Integer: - Specifies the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Real: - Specifies the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), and Standard (e.g. 98.6). Default is Standard.

Printing tab:

Screen Element - Allows you to select the screen element (a graphical part of VEE) for which you'll set the shade of gray to use when printing.

B & W Printer Darkness - Allows you to select the shade of gray to use for each screen element, when it prints on non-color printers. The defaults are usually fine for most printers.

Print Magnification: - Specifies the magnification used when printing a VEE program or part of a program. Use a lower number for a smaller image on the printout. To make a printout of a maximized screen fit on one page, the default printing magnification is set to 75%.

Print Header and Index Page - When this box is checked, each page of a printout of the VEE program will contain a two-line header showing the date and time, the program file name, and a page number. At the end of the printout, an index page will be printed which shows the page numbers of the indexed items.

Print Program Explorer - When this box is checked, the VEE program printout will show the information contained in the Program Explorer window.

Print Cover Page - when this box is checked, the first page of the VEE program printout will show the following:

A graphic of the Agilent VEE product logo.

The file name of the program being printed.

The file format under which the program was saved.

The revision code of the VEE software being used (such as 6.0, etc.).

The current VEE execution mode (VEE 6, etc.).

The Main UserObject Description file (if one has been entered).

Print I/O Configuration - when this box is checked, the instrument configuration’s expanded tree view is printed. You can see the instrument configuration in I/O [image] Instrument Manager…

To generate a plot, interactively choose the Print menu entry from the display's object menu. If the current Printer Setup is in the Print to File mode, the file or directory name specified will be used.

The entire view of the display object will be plotted, and scaled to fill the defined plotting area, while retaining the aspect ratio of the original display object. By re-sizing the display object, you can control the aspect ratio of the plotted image. By making the display object larger, you can reduce the relative size of the text and numeric labels around the plot.

Web Server tab:

Enable Server - Allows you to turn on VEE’s built-in Web server. The default is off. The Web server lets you monitor and troubleshoot a VEE application from a remote Web browser using standard HTTP 1.0 protocol. VEE must be running on a system that is connected to a network.

Root Directory: - Allows you to specify the location of files accessible to remote Web browsers. The default is ~installDir/www. Do not put private files in this directory or in any of its subdirectories since they are viewable by any Web browser with access to the host system. The file index.html is installed in the default root directory. This file is the default Web server home page, which you may adapt to your needs. If you change Root Directory, move index.html to the new location and do not change its file name.

HTTP Port Number: - Allows you to specify the port number for the Web server. The default is 80. The only times when you may need to change the default port number is when another Web server, such as another VEE, is running on the same system, or if you want to restrict access to VEE’s Web server. Do not use a port number that has already been allocated. Allowed values range from 0 through 65535. For a list of currently allocated ports see the services file:
Windows NT: \Winnt\system32\drivers\etc\services

Server Timeout (sec): - Allows you to set the maximum time the Web server waits for VEE to process Web server commands. The default is 60 seconds. If the VEE program is busy performing a time-consuming activity, a timeout message is sent to the Web browser.

Log File: - Allows you to specify the location for the log file http.log. The default location is a temporary directory such as C:\tmp\http.log. If the log file does not exist already, it is created when you make any changes in Default Preferences. The log contains a record of all incoming HTTP requests processed by the Web server. Data is appended to the log file, so you must monitor its size.

I/O tab:

IO Preferences

 Enable Pre 8.0 Legacy IO - When this box is checked, Instrument Manager will search old-style SICL devices. By default, Instrument Manager does not search those devices.

MATLAB tab:

 Use MATLAB installed on your machine - When this box is checked, VEE will use the MATLAB installed on your machine. When this box is unchecked, VEE will use the built-in MATLAB Script Engine shipped with Agilent VEE. Refer to MATLAB Script Overview for differences between these two versions of MATLAB.

Version - allows you to select a MATLAB installed on your PC to use.

Location - automatically displays the location of the MATLAB you selected.

After changing the MATLAB to use in VEE, you must save the configuration and restart the Agilent VEE to let the change take effect.

Notes

After you enable the VEE Web server and set its attributes, you can access the Web server from any Web browser that supports the HTTP 1.0 specification (any commonly available browser). Enter a URL in one of the two following formats:

http://hostname{:port}{/file}

or

http://hostname{:port}{/command}{?parameter}

Where:

hostname (required) identifies the host system on which VEE is running. When used alone in a URL, this opens the Web server home page index.html.

port (optional) identifies the Web server’s HTTP Port Number if not using the default value.

file (optional) identifies a directory and/or file relative to the Root Directory for the browser to open. You can include a file name extension, such as .jpeg or .html.

command (optional) specifies a command supported by the Web server letting you monitor, troubleshoot, and control a VEE program from the browser. Commands are described below.

parameter (optional) specifies a parameter required by a command. Parameters are described with the commands below.

The Agilent VEE Web server supports the following commands:

ViewVEE displays the entire VEE window.

ViewMainDetail shows the Main window's detail view. An error appears if the program was saved as a secured RunTime program.

ViewMainPanel displays the Main window's panel. An error appears if the Main window doesn't have a panel.

ViewExecWindow displays an VEE Execution window. An error message appears if no Execution window exists.

ViewDetail?UserFuncName displays the detail view of a UserFunction named UserFuncName. An error message appears if UserFuncName doesn't exist or has been saved as a secured RunTime file. The view is sized such that all objects in the UserFunction are visible, even if the current UserFunction window size is smaller.

ViewPanel?UserFuncName displays the panel view of a UserFunction named UserFuncName. An error message appears if UserFuncName doesn't exist or doesn't have a panel.

ViewError shows the Error window of the current program.

The following examples show URLs that you can enter in a Web browser. They assume that VEE is running on a networked system with the host name my_system, the Web server is enabled, and it is using the default HTTP port number 80.

http://my_system/public_docs/page.html
Displays the file page.html in the directory public_docs. This directory and file are located on the host system relative to the Web server’s root directory.

http://my_system/ViewExecWindow
Displays the VEE Execution window.

When Save is pressed, default preferences are stored in the defaults file VEE.RC in the VEE program installation directory for MS Windows). Some of these properties are saved in your program as well as the defaults file. These include the choices in the Environment and Trig Mode groups on the General tab, and the number format on the Number tab. The colors and font values are saved in the program only if the Save colors and fonts with program box is checked on the File [image] Save dialog. Also for colors and fonts, only the settings you change are saved in the defaults file.

If OK is pressed, the changes are valid only for the current work session.

If Reset is pressed, your current settings are discarded and the defaults file is re-read.

If Cancel is pressed, the changes you made are canceled.

Location

File [image] Default Preferences

See Also

Align, Clean Up Lines, Delete Variable, Get Variable, Set Variable, Show Data Flow, Program Explorer, and Properties (Object)

To Change Default Colors

To Change Default Fonts

To Change the Number Format

To Change the Printing Preferences

To Set Up a Printer


Delay

An object that waits a specified period of time before activating its Done data output terminal.

Use

Use Delay to delay execution of a thread segment for a specified number of seconds.

Example

Use Delay as a time out in a dialog box created with a UserObject.

Open View Parameters

Enter the number of seconds delay in the edit field. If you add a data input pin, the value supplied to that pin determines the delay period in seconds.

Notes

The delay value is specified in seconds and has a resolution dependent on the system clock and the nature of the program in which the Delay is operating. You can set the value for the Delay through a data input.

The delay interval is measured from the time when the sequence input pin is activated. After the specified interval, the Done data output terminal is activated. Note that Delay is "asleep" while it is waiting, thereby allowing other objects the opportunity to operate.

In most cases, either the Done data output terminal or the sequence out pin may be used to continue propagation after the Delay time expires. However, when the Delay object is part of a thread containing other objects executing in parallel, the sequence out pin may not fire until a much longer time has elapsed. This is because sequence out pins are fired only when there are no other objects which may execute. To ensure that the delayed thread will continue at the end of the Delay period, use the Done data output terminal, which always fires at the end of the Delay time period.

Location

Flow [image] Delay

See Also

Instrument Event, Interface Event, OK, On Cycle, Properties (Object), and Object Menu

To Set a Timeout


Delete (Object Menu)

Removes this object from the panel or detail view.

Use

Use Delete to remove the object from the detail or panel view. Note that when deleting the object from panel view, the object remains on the detail view.

Deleting an object from detail view also removes it from the panel view.

Notes

Delete does not modify the clipboard (ie. for Paste).

You can undo a Delete by pressing CTRL+Z, by selecting Edit > Undo from the main menu, or by selecting [image] from the taskbar.

Short Cuts

You can quickly delete an object by double clicking the object menu selection box in the upper left corner of the object.

Location

On the object menu [image] Delete

See Also

Cut, Object Menu, To Undo an Operation, and Properties (Object).

To Delete Objects from a Panel


Delete Directory

Deletes a given directory.

Location

System [image] Directory [image] Delete Directory


Delete File

Deletes the file at the given path location.

Location

System [image] File [image] Delete File


Delete Library

An object that deletes (unloads) a library of UserFunctions, Compiled Function definitions, or Remote Function definitions from a running program.

Use

Use Delete Library to delete a library from your VEE program. The action taken depends on the type of library:

UserFunction - Delete Library deletes from the VEE program the UserFunctions previously loaded with an Import Library object. This deletes only the UserFunctions contained in the library named in the Library Name field.

Compiled Function - Delete Library detaches a shared library from the VEE process. However, the file containing the shared library is actually detached only when the last library pointing to that file is deleted. That is, if you have several different libraries pointing to the same shared library file (with either the same or a different definition file), the shared library file is detached from the VEE process only when there are no more libraries using the attached code. The operating system will not allow you to move or delete a shared library file once it is attached to a process. You must use the Delete Lib option in the Import Library object to detach the code if you want to create a new shared library file.

Remote Function - Delete Library shuts down the remote VEE process and removes the Remote Function definitions from the local VEE process. Delete Library actually shuts down the remote process when the last library that references the remote process is deleted on the local host.

Open View Parameters

Library Name - In this field, enter the name of the library that you want to delete.

Notes

Delete Library is generally used for advanced operations where you want to dynamically load, and then delete, library objects from a running VEE process. This greatly reduces the memory requirements of the VEE process.

The Delete Library object will accept a single Data Input terminal. The default name of the input terminal is LibraryName.

Location

Device [image] Delete Library

See Also

Call, Edit UserFunction, Import Library, UserFunction, UserObject, and Properties (Object)


Delete Line

Removes the line between two pins.

Use

Use Delete Line to eliminate wrong connections or to modify connections in your program. Select Delete Line, then click on or near the line to be deleted.

To exit this mode without deleting a line, click on an empty space on the work area, away from any lines.

Notes

To view the endpoints of a line (without deleting it), place the cursor over the line momentarily. This will highlight the line and show the endpoints. It will also show the value carried by the line.

Delete Line is not available when the program is running.

Delete Line can be undone.

Short Cuts

While holding down CTRL+Shift place the pointer over line(s) and click the left mouse button to delete lines.

You can delete a series of lines this way, one at a time.

Location

Edit [image] Delete Line

See Also

Cut, To Undo an Operation, and Line Probe.


Delete Terminal

A menu item.

Use

Use Delete Terminal to access the following features which delete terminals:

Input - Used to delete a data or control input pin that was added to the object. After selecting Input, select the pin to be deleted from the dialog box displayed. The pin and any connections to it are deleted. If two pins have identical names, VEE deletes the pin based on the order that the pins appear in the list.

Output - Used to delete a data or error output pin that was added to the object. After selecting Output, select the pin to be deleted from the dialog box displayed. The pin and any connections to it are deleted. If two pins have identical names, VEE deletes the pin based on the order that the pins appear in the list.

Notes

Input is available only if the object has input pins that may be deleted. Some pins cannot be deleted.

Output is available only if the object has output pins that may be deleted. Some pins cannot be deleted.

Short Cuts

You can quickly delete a data terminal by placing the cursor over the terminal view area and then pressing CTRL+D.

Location

On each object menu:
Delete Terminal [image] Input…

Delete Terminal [image] Output…

See Also

Add Terminal, Line Probe, Object Menu, and Properties (Object).


Delete Variable

An object that deletes the value of a variable that has already been created in the execution of the current program.

Use

Use the Delete Variable object to delete a variable by name or to delete all variables currently set in the program. The variable must have been created previously by a Set Variable object within the program.

Open View Parameters

By Name - The open view displays a field for the name of the variable. The name is not case sensitive (either lower-case or upper-case letters may be used). Thus globalA is the same variable as GLOBALa. The name field may be added as a control input.

All Variables - Deleting all variables will delete all declared variables of all scopes, and all undeclared variables. The name field is grayed out (unavailable).

Notes

The Delete Variable object will error if the variable referenced by name does not exist. To avoid getting this error, add an error output pin to the Delete Variable object.

When the Delete Variable object has executed, the variable referenced by name (or all variables) are deleted, just as if they never were created. Subsequent use of the variable in Get Variable objects will error since the variable does not exist.

Deleting variables when they're not needed anymore with the Delete Variable object saves memory and helps you better manage your variables.

In Default Preferences, if Delete Variables at PreRun is on (the default), all variables are deleted before your program executes. If Delete Variables at PreRun is turned off, variables will not be deleted, and you must program carefully to avoid propagating invalid data.

For more information about programming techniques that effect the cleanup of ActiveX references, see the CreateObject topic.

Location

Data [image] Variable [image] Delete Variable

See Also

Default Preferences, Get Variable, Set Variable, WatchWindow, and Properties (Object)

To Delete a Variable and Releasing ActiveX References


DeMultiplexer

An object that directs the input value to a selected output pin.

Use

Use DeMultiplexer to direct the input data to a particular output pin. The output that is activated depends on the value of the address input.

Notes

DeMultiplexer has two inputs, one for data output and one for the address value (which determines the output to be propagated). Only one output is propagated each time the object operates. If the value of the address input is not within the range of the number of outputs [0 [image] (N-1)], an error is returned. Additional outputs can be added to the object. Outputs can be deleted, but then the following outputs (if any) are renumbered in order.

Location

Device [image] DeMultiplexer

See Also

If/Then/Else, JCT, Properties (Object), and Object Menu


Description

Accessible from the object menu for information about an object, or from the title bar menu for information about the main program, UserObject, or UserFunction.

Displays an editable Rich Text Format (RTF) dialog box that displays user-supplied information. There is a default Description, which demonstrates the capabilities of the dialog box, that is displayed when the Description dialog box is opened. To create your own default Description, edit the description.rtf file in installdir\templates. If you want an empty description dialog box, edit the description.rtf file and leave it empty.

Use

Objects with a description have a small red triangle in the upper right corner.

Use Description to document an object, and explain how or why it's used. Or from the title bar menu, use Description to document the entire file.

To write a description, click in the text area and type the description, or cut and paste a description from a RTF file. Click OK when you're finished.

Open View Parameters

OK - Saves the description information with the program.

Cancel - Cancels current changes to description, and closes Description window.

Insert File - Opens a Select File to Insert window. You can insert a file created in any editor capable of reading/writing rtf files such as Wordpad or Microsoft Word.

Clear All - Clears all content from the Description window. To recover canceled text, press Cancel, then re-open the Description window.

Font and Color - Opens a Font window. You can change the colors and fonts of selected text.

Notes

You can edit the text area using the usual VEE edit functions.

When printing using Print All with Print All Objects selected or printing using Print Objects, the description for the object will also be printed.

Since Description is an RTF dialog box, you can use an RTF enabled application to create beautifully formatted text that includes multiple fonts, colors, tables, active URLs, etc.

You can print the Description text but it is always printed as text only.

Location

On each object menu [image] Description

or

On each title bar menu [image] Description

See Also

Note Pad, Object Menu, Create RunTime Version, and Object Menu


Dialog Box

A menu item.

Use

Use Dialog Box to access the following prepared dialog box objects:

Text Input

Int32 Input

Int64 Input

Real64 Input

Message Box

List Box

File Name Selection

Location

Data [image] Dialog Box

See Also

File Name Selection, Int32 Input, List Box, Message Box, Real64 Input, Text Input, and UserObject.

About Built-In Dialog Box Objects

To Use a Data Input Dialog Box


Direct I/O

An object that writes data to and reads data from an instrument using transaction statements.

Use

Use Direct I/O to output and input a variety of encodings and formats to instruments.

Object Menu

Show Config - Displays the instrument configuration.

Upload State - Uploads the current instrument state to a learn string, and associates this state with this particular instance of the Direct I/O object. Supports GPIB and message-based VXI devices that support learn strings.

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Open View Parameters

Direct I/O Actions:

READ - Reads data from an instrument using the specified encoding and format.

WRITE - Writes data to an instrument using the specified encoding and format.

EXECUTE - For a GPIB instrument, sends either a Selected Device Clear, Go To Local, Remote, or Group Execute Trigger command. For a serial instrument, sends Break or Reset. For a GPIO instrument, sends Reset. For a VXI message-based instrument, sends either a Selected Device Clear, Go To Local, Remote, or Trigger command.

WAIT - Waits the specific number of seconds before executing the next transaction. For a GPIB instrument or a VXI message-based instrument, wait until the bitwise AND of the serial poll response with the mask is either zero (ALL CLEAR) or non-zero (ANY SET).

For GPIO instruments only, the READ action allows IOSTATUS and the WRITE action allows IOCTL.

For VXI instruments only, the READ and WRITE actions allow REGISTER: and MEMORY:. The WAIT action also supports the ability to wait until the value in a memory or register offset AND a mask value satisfy the ANYSET, ALL CLEAR, or EQUAL.

Direct I/O Encodings:

TEXT - Writes all data types in human-readable form. VEE numeric data is automatically converted to text as it is written.

BINARY - Writes all data types in an machine-specific binary format.

BINBLOCK - Writes all VEE data types in binary files with IEEE 488.2 definite length block headers.

When using BINBLOCK with an instrument that outputs a terminating line-feed, select End byte (LF) so that VEE will consume the terminating line-feed. If the instrument does not output a terminating line-feed, select No END byte.

CONTAINER - Writes all data types in a platform-independent text format.

Short Cuts

You can quickly add a data terminal by placing the cursor over the input or output terminal display area and then pressing CTRL+A. Each press of CTRL+A adds an additional data terminal.

You can quickly delete a data terminal by placing the cursor over the terminal view area and then pressing CTRL+D.

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To paste a transaction from the "kill" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Control pins are available as inputs to programmatically change the device address and timeout period. Timeout period is measured in seconds for these transactions.

Location

I/O [image] Instrument Manager

See Also

Advanced I/O, Component Driver, Formula, Instrument Manager, Panel Driver, and To/From VXIplug&play.

To Increase I/O Performance

To Read Data Using Direct I/O

To Use a Direct I/O Object

To Edit a Transaction


Directory Exists

Tests to see whether a given directory exists.

Location

System [image] Directory [image] Directory Exists


Do

An object that creates a branch point to control the execution flow of a thread.

Use

Use Do to create a branch point; the object connected to the data output pin is activated before the object connected to the sequence output pin. Note that this forces the order in which objects operate.

Location

Flow [image] Do

See Also

Break, Start, Properties (Object), and Object Menu


Domain Name

Retrieves the domain name where the host machine is a member.

Location

System [image] Environment [image] Domain Name


Drop-Down List

See Selection Control.


Edit UserFunction

A menu selection that allows you to edit a locally-created UserFunction within a program. You may also view (but not change) a UserFunction imported with a library.

Use

Use Edit UserFunction to edit a UserFunction created locally within a program by executing Make UserFunction from the object menu of a UserObject. If you have saved a series of UserFunctions in a library file, you will have to open the library file to edit those UserFunctions.

Notes

When you select Edit UserFunction, a dialog box appears listing the available local UserFunctions to edit. Once you select a UserFunction, a window is created that displays a work area showing the functionality of the original UserObject from which the UserFunction was created. You can edit this work area just as you would edit any UserObject. When you have finished, close the window. When you save the file, the edited UserFunction will be saved with it.

While editing a UserFunction you can switch between the Panel and Detail view by using the Panel and Detail icons from the title bar.

When viewing a UserFunction imported with a library, you cannot change the UserFunction. However, to aid in debugging, you may set breakpoints, and open/iconize/move objects. These changes will not be saved to the library file.

Shortcuts

From the Program Explorer, double click a UserFunction to edit it.

Location

Edit [image] Edit UserFunction

Object menu of Call Function [image] Edit UserFunction

See Also

Call, Create UserFunction, Delete Library, Import Library, UserFunction, and UserObject.

To Edit a UserFunction


Ends With

Returns a boolean true if the given string ends with the test value.

Location

System [image] String [image] Ends With


Error Output (Object Menu)

Adds an error output terminal to the object.

Use

Use Error Output to allow your program to trap and process VEE errors. If an Error pin is on an object and the object encounters an error, no error dialog box is displayed. Instead, the error number is output to the Error pin.

If an error is trapped, the error output pin and the sequence output pin are activated; no data is output on the data output pins.

The error output pin outputs a Scalar Int32 container with the value of the error number that was generated.

Notes

Error Output is available from almost all objects. Some objects, such as Note Pad, never return an error, therefore, they do not allow the addition of an error output pin.

An error output terminal outputs the error number of the VEE error. It does not output the meaning of the number or any recovery information. Error information is available under the Error Codes topic under Help [image] Contents and Index

Use errorInfo() to determine error information for the last error trapped when using error output pins. After the error is trapped, execute an errorInfo() object to output a record that contains all the information that would be displayed in an error dialog box.

A Raise Error object in a UserObject can generate an error that may be trapped by the error pin of an enclosing UserObject.

The error pin on a UserObject traps any errors for any object in the UserObject.

Location

On each object menu [image] Add Terminal [image] Error Output

See Also

Add Terminal, Delete Terminal, errorInfo, Object Menu, Raise Error, and UserObject.

To Trap an Error


Execute Program

An object that starts an MS-DOS or Windows process.

Use

Use Execute Program to start MS-DOS or Windows processes, including executable programs, operating system commands, or batch files. The PC Execute object returns an exit code from the program that was executed. If Wait for prog exit is set to No, the exit code output terminal does not propagate any return value.

Open View Parameters

Run Style - If the program you want to execute runs in a window, Run Style specifies the window style:

Normal runs the program in a standard window.

Minimized runs the program in a window minimized to an icon.

Maximized runs the program in a window enlarged to its maximum size.

Wait for prog exit - If Wait for prog exit is set to Yes, VEE runs the external process, and waits until the external process terminates before activating the sequence output pin of the Execute Program object.

If Wait for prog exit is set to No, VEE runs the external process, but activates the sequence output pin of the Execute Program object without waiting for the external process to terminate.

Prog with params - The program you want to run. Here are some examples of what you might type into this field:

C:\MYDIR\MYFILE.BAT

"\Program Files\Windows Media Player\mplayer2.exe" "\WINNT\Media\Mozart's Symphony No. 40.rmi"

www.favorite_site.org/index.htm

Path names containing spaces must be enclosed in quotes, as shown in the next-to-last example.

In the last example, the known suffix ".htm" starts your Internet browser and loads the specified URL. If the browser is already running, it loads the specified URL.

Working directory - Points to a directory where the program you want to execute can find files it needs. So, if you want to run the program nmake using the makefile in the directory c:\progs\cprog1 use these parameters:

In Prog with params:, enter nmake.

In Working directory:, enter c:\progs\cprog1.

Notes

Execute Program is not transaction based. You cannot communicate with external processes using transactions.

If you have included the appropriate path in the PATH variable, you don't need to include the path in the Prog with params field. Set the PATH variable in AUTOEXEC.BAT file for Windows 98 or User Environment Variables (Main / Control Panel / System) for Windows NT.

To execute a .EXE file, you don't need to include the suffix in the Prog with params field. However, for .COM and .BAT files you do need to include the suffix.

If the action specified in Prog with params does not cause a new instance of a program to start, the Execute object does not wait for the program to exit, even if Wait for prog exit is set to Yes. The exit code terminal does not propagate an exit code in this case. One example of this behavior is "executing" a URL when your Internet browser is already running. The specified URL is opened in the running browser, and VEE does not wait until you eventually close your browser. Other common examples of this behavior are passing files to existing instances of a word processor or a spreadsheet editor. Note that the designer of the external application (browser, spreadsheet, etc.) determines whether a new instance is started or the existing instance is used in these cases.

The Execute object uses the ShellExecuteEx() Win32 API.

Location

I/O [image] Execute Program

See Also

To/From DDE and Properties (Object)


Execution Window

A selection on the View menu.

Use

If your Main UserObject has a panel, and ShowPanelOnExecute is enabled on Main's Properties Window, then that panel will appear inside the Execution Window when you run your VEE program. This will allow you to see both your Main object window as well as the Execution Window. Also, the Execution Window shows you what your executable program will look like when run in VEE Pro RunTime.

The Execution Window can be moved, resized, maximized, minimized or moved to the bottom of the window stack, but it cannot be closed.

The name that appears in the title bar of the Execution Window can be set from the object menu on the Main window. From the Main object menu, select Properties, then change the PopUpPanelTitle.

Location

View [image] Execution Window

See Also

Add To Panel, Main, and Create RunTime Version.

About the Agilent VEE Pro RunTime Product.


Exit

Exits (quits) VEE.

Use

Use Exit to end this work session with VEE.

Notes

If your program changes have not been saved when you select Exit, you are prompted to save them.

You are not allowed to Exit when a program is running. Use the Stop object to exit a running program.

Short Cuts

Press CTRL+E to exit. On the window control button in the upper-left corner of the VEE window, either double-click on the button, or click on the button and choose Close from its menu.

Location

File [image] Exit

See Also

Raise Error, Exit Thread, Exit UserObject, New, Open, and Stop.


Exit Thread

An object that stops the execution of a thread.

Use

Use Exit Thread to terminate the execution of an independent thread. Exit Thread only stops the execution of the thread on which it resides.

Location

Flow [image] Exit Thread

See Also

Break, Raise Error, Exit UserObject, Start, Stop, Properties (Object), and Object Menu

To Stop a VEE Program


Exit UserObject

An object that stops the execution of a UserObject.

Use

Use Exit UserObject to stop the execution of all threads in the UserObject and start execution in the next object after the UserObject in the program. Any data sent to the UserObjects output terminals before the Exit UserObject was encountered, is passed to the appropriate succeeding object(s) by activating these outputs.

Use Exit UserObject to make an early exit from a UserObject.

Location

Flow [image] Exit UserObject

See Also

Create UserObject, Raise Error, Exit Thread, Start, Stop, UserObject, and Properties (Object)

To Exit a UserObject Early


File Exists?

Checks whether a file at a given path exists.

Location

System [image] File [image] File Exists?


File Name Selection

An object that displays a pop-up dialog box that displays a list of files to the user.

Use

Use File Name Selection to display a list of the files on a disk drive to the user. The user responds by selecting one of the choices on the dialog box. File Name Selection is very useful to interactively request file names to be used in To File and From File objects.

In the pop-up dialog box, when a file selection is made and the OK button is pressed, the selection is output on the File Name output pin. When the Cancel button is pressed, a 1 is output on the Cancel output pin.

Open View

Prompt/Label - The string that prompts the user to select a file name. You may add this parameter as a data input. Default is Enter File Name:

Initial Directory - The directory that is initially shown in the File Name Selection pop-up dialog box. You may add this parameter as a data input. Default is the directory from which you stared VEE.

Initial File/Wildcard - Allows you to set a file name as the default or to filter a set of file names by using wildcard characters. You may add this parameter as a data input. Default is *.*.

Select File For: Reading | Writing - When you select Reading, the user must select an existing file name from the pop-up dialog box. If the user types a nonexistent file name into the pop-up dialog box and presses OK, they are prompted to enter an existing file name.

When you select Writing, the user may type a new file name or select an existing file name from the pop-up dialog box. If an existing file name is chosen, a warning dialog box pops up asking if it's OK to overwrite the file. If the user presses Yes, the file name is output to the File Name output pin. If the user presses No, the user is returned to the File Name Selection dialog box to select another file name. You may add this parameter as a data input.

Notes

The pop-up location of the File Name Selection dialog box is not selectable. This dialog box always appears near the upper-left corner of the VEE window.

To respond to the pop-up dialog box using only the keyboard: when the dialog box pops up, use Enter and Esc keys. Or use the Tab key to move between the buttons and the selection area; move through the choices with the arrow keys, and select the file name with the Space bar.

The pop-up dialog box is only displayed while the program is running. While the pop-up dialog box is displayed, the entire program pauses execution, then continues when the dialog box is closed.

The Input Terminal "Dialog Mode" accepts two text strings, either Writing or Reading. These strings are case sensitive.

Location

Data [image] Dialog Box [image] File Name Selection

See Also

From File, Int32 Input, List Box, Message Box, Real64 Input, Text Input, To File, UserObject, and Properties (Object)

To Select a File Name Programmatically


Fill Bar

An object that displays a Scalar numeric value graphically using a color bar.

Use

Use Fill Bar to display a numeric value on an analog scale with a color bar, and an optional digital numeric field.

Open View

The minimum and maximum values of the Fill Bar are set on the open view of the object by clicking on the present value and typing in a new value. Tic marks and their labels are automatically calculated and displayed. The minimum value must be less than the maximum value.

These values may also be added as control inputs.

Properties

Orientation - Selects the how the Fill Bar is displayed. Default is Vertical.

 ShowDigitalDisplay - If the property is True, a digital display of the input value is displayed at the bottom of the open view of the object. If the property is False, the digital display is not displayed and the object operates faster. Default is True.

ShowTics - Controls visibility of scale’s tic marks and labels. Default is True.

 Logarithmic - When turned on, changes scale from linear to logarithmic. Default is False.

 Label Spacing - Controls which tic marks are labeled with the scale values. Default is Every Other Tic.

HighColor - Specifies the color used for the highest range (i.e., greater than High Limit).

High Limit - Defines the numeric lower limit for the highest range. This value must be greater than or equal to the Low Limit. You may add this value as a control input, which disables this property's edit field.

 MidColor - Specifies the color used for the middle range (i.e., less than or equal to High Limit and greater than Low Limit).

 Low Limit - Defines the numeric upper limit for the lowest range. This value must be less than or equal to the High Limit. You may add this value as a control input, which disables this property's edit field.

 LowColor - Specifies the color used for the lowest range (i.e., less than or equal to the Low Limit).

NumberFormat - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

The input data must be Scalar and able to be converted to Real64 (Complex, PComplex, Spectrum, and Coord must be first "unbuilt".)

The Low Limit must be less than the High Limit.

To use only 2 ranges of color, set the Low Limit equal to the High Limit.

To use only 1 color, set the Low Color, Mid Color, and High Color to the same color.

Short Cuts

To quickly change the orientation of the Fill Bar, just resize it to the desired shape. It will automatically change orientation.

Location

Display [image] Indicator [image] Fill Bar

See Also

AlphaNumeric, Color Alarm, Logging AlphaNumeric, Meter, Tank, and Thermometer.

To Show an Analog Display of Data


Find

This menu choice provides a dialog box to search for text strings and certain object properties in a VEE program.

Use

The Find feature provides you with a convenient method of performing text string searches in VEE programs. This makes it easy to locate specific text within program objects, and will also allow searches for certain other object properties, such as an object's title bar color or background color.

However, Find will not search for the following:

Panels or objects on panels.

Lines or line values.

Terminal values.

Dialog Information

The Find dialog box includes a single-line text field for entering a searchable text string, and provides several options for configuring the search specifications. The dialog box features are:

Find What: - The text string to be searched for is entered on this line. If you leave this line blank, a search will match any and all text.

Search in: - Allows you to limit the scope of the text search to only certain segments of the VEE program. The default is to search Entire Program.

Find - The Find button begins the text search using the search parameters that the user specifies on the General and Advanced tabs of the dialog box.

Stop - The Stop button halts the search process. Any matches found up until the search process was stopped are retained.

Help - The Help button invokes the on-line help information for the Find dialog box.

A Status Bar is located at the bottom of the Find dialog box. The Status Bar indicates the status of the search process. The information in the Status Bar will update as new matches are found.

Properties

General tab

The General options tab provides a set of constraints for limiting the general text search. The options are:

Match Case - If checked, the text must match the user-specified search string exactly. Default is off.

Find all matches on each object - Default is off.

Search nested UserObjects - Default in on.

Show occurrences that - further constrains the search as follows:

Contain search text - Default is on.

Exactly match search text - Default is off.

Begin with search text - Default is off.

End with search text - Default is off.

Advanced tab:

Clicking on the Advanced tab will bring up a new set of options on the Find dialog box. The options on the Advanced tab provide a way to constrain a search based on object types and object characteristics. The Property and Value buttons on the Advanced tab are used in combination to define the search criteria. Once a Property button has been defined, its associated Value button also must be defined.

Property and Value - There are three buttons in the Property column and three buttons in the Value column. Clicking on one of the buttons in the Property column brings up a Property Name dialog box which lists the names of specific search properties. For each Property Name selected, a value must then be selected by clicking on the adjacent Value button. The Property and Value combinations are paired as follows:

Object Type (default) - when this Property Name is selected, the Value button will default to All Types. Clicking on the Value button will bring up the Select Object Type(s) dialog box. This dialog box lists all VEE functions that are capable of opening an object in the VEE workspace. For an explanation of each of the object types that are available, refer to that object type's specific section in Help.

Note that in the Select Object Type(s) dialog box, all of the object types available are pre-selected by default. In order to select just one, or several object types, click the Clear All button on the dialog box, then use the left mouse button to select the specific object types desired. Any and all selected object types may be unselected by clicking on the Clear All button. A Property button can also be assigned a Property Name other than Object Type. A few property name examples, and their associated Value are described below:

- Description - valid values are any user-defined Description entered by the user in the Value field.
- Device name - valid values are any user-defined Device name entered by the user in the Value field.
- Popup Panel Title Background Color - valid values are any color from the VEE color map. The default color for this value will be the color specified by the user in the Default Preferences dialog box. Clicking on the Value field will open the Select Color for Object Title dialog box. The user can use the left mouse button to select any color from the color palette in this dialog box.

Reset - The Reset button defaults the first Property button to Object Type and defaults the first Value button to All Types. The remaining two pairs of Property and Value buttons on the Advanced tab will be cleared of any selected options.

Short Cuts

Press Ctrl+F to open the Find dialog box.

To limit the scope automatically, open Find from the Program Explorer by clicking with the right mouse button on a particular context, such as a UserFunction or UserObject.

Location

Edit [image] Find...

See Also

Default Preferences and Find Results.

To Find Objects by Searching for Properties

To Find Objects by Searching for Text


Find Results

Displays a tool window that lists the results of the last Find search.

Use

Use Find Results to display a tool window that shows the results of the last execution of a Find text search. If a Find text search has not been executed, then the Find Results menu item will be grayed out (unselectable).

The Find Results tool window will also be displayed when you click on the Find button on the Find dialog box.

Window Information

The title bar of the Find Results tool window provides a summary of the Find search, including how many matches were found, as well as the total number of VEE objects. Below the title bar are several control buttons, the specific search text that was used, and the search scope (Entire Program, etc.).

Toolbar buttons - The control buttons provide short cuts to viewing the Find Results. The control buttons include:

Display previous item - Displays the previous match in the Find Results list.

Display next item - Displays the next match in the Find Results list.

Find - Restores the Find dialog box.

Clear - Removes all results in the Find Result list.

Find: - This area displays the specific text that was searched for, enclosed in quotation marks and the scope of the search. The default is the entire program.

Object Location - The path name to the UserFunction or UserObject where the match was found. In the case of nested VEE UserObjects, this is the path through each of the nested objects.

Object Title - The title of the object on which the text was found. This title is set via the Object Properties.

Object Type - The type of VEE object on which the text was found (such as a Formula object, Constant object, etc.).

Text Found - The text that was found somewhere in the object. This text could be in the object title or somewhere internal to the object itself.

Adv - The "Adv" label will enable if the user selects some advance options in the Find dialog box.

Short Cuts

Press Ctrl+R to open the Find Results tool window.

You can also change the sorting order of a column in the tool window by clicking on the column header.

Location

Edit [image] Find Results

See Also

Find

To View Results of a Find Operation


For Count

An object that activates its data output pin a specified number of times.

Use

Use For Count to execute a subthread a specified number of iterations. The output of a For Count can be used as a value for succeeding objects in the subthread.

Open View Parameters

Enter the number of iterations in the entry field or as an input.

Notes

The For Count output value is a Real64 scalar ranging from 0 to n-1 where n is the specified count value. All access to unmapped array objects is zero-based, therefore For Count is ideally suited for traversing the dimensions of such objects when required. The For Count value is the dimension size.

If the specified For Count value is zero or negative, the output is not activated, but the sequence output pin is.

Execution of the subthread hosted by the For Count output continues until one of the following occurs:

All objects that can, have operated. The subthread is deactivated, the iteration counter is incremented, and, if the count value is less than the specified count, the subthread is reactivated by refiring the For Count output with the new iteration value.

A Break object operates. The subthread is deactivated and the sequence output pin is activated. Note that the value that remains on the For Count output is the same value present when the Break was encountered.

A Next object operates. The subthread is deactivated and the iteration counter is incremented. If the count value is less than the specified Count, the subthread is reactivated by refiring the Count output with the new iteration value, and execution of the subthread proceeds as usual. If the iteration counter has reached the Count value, the sequence output pin is activated.

When the subthread hosted by the For Count object finishes an iteration, all data containers sent during the previous iteration are invalidated before the next iteration. This prevents "old" data from a previous iteration from being reused in the current iteration. However, if flow branching is present within the iterative subthread, some objects may not execute on every iteration. Thus, data containers sent by those objects may be invalidated before other objects can execute on the data. To obtain the desired propagation in this case, use the Sample & Hold object.

Location

Flow [image] Repeat [image] For Count

See Also

Break, For Log Range, For Range, Get Values, Next, On Cycle, Sample & Hold, Set Values, Until Break, Properties, and Object Menu

(Object)

To Loop Part of a VEE Program


For Each

The For Each statement iterates arrays or collections.

Use

For VEE array support, the For Each statement handles any VEE array of any number of dimensions (1-10), any dimension sizes, and any type. It will work in all ExecModes.

For COM support, the For Each statement handles any COM (ActiveX) object that can be enumerated or looped. This type of object usually has a "Count" property and an "Item()" method to show it is a collection, though, strictly speaking, these are not required. COM/ActiveX is available in ExecModes 5 and higher.

For .NET support, the For Each statement handles any .NET object that can be enumerated or looped through, for example StringCollection. This type of object also usually has a "Count" property and an "Item()" method to show it is a collection, though, strictly speaking, these are not required. .NET objects are available in ExecModes 6&7 and higher.

Example

Note in the example that it takes three objects to process the one-dimensional array using the For Count method, while only the For Each object is needed in the other approach. Of course, as additional dimensions are added to the array, the For Count method becomes progressively more complex while the For Each method handles up to ten dimensions without changing.

The For Each object will not work with records.

Location

Flow [image] Repeat [image] For Each


For Log Range

An object that activates its data output pin a specified number of times.

Use

Use For Log Range to execute a subthread for a specified number of iterations. Use For Log Range to specify a beginning, end, and increment, and generate output values that are evenly distributed along the log 10 scale.

Open View Parameters

From - The beginning value of the iteration loop.

Thru - The ending value of the iteration loop. When the value of the iterator is greater or equal to the Thru value, the loop is completed.

/Dec - Determines the spacing of values from the iterator. The 0th value is From. The nth value is From*exp10(n/(/Dec)).

From, Thru, and /Dec may be added as inputs.

Notes

The For Log Range output value is a Real64 scalar ranging from From to Thru.

Execution of the subthread hosted by the For Log Range output continues until one of the following occurs:

All objects that can, have operated. The subthread is deactivated, the iteration counter is incremented by the /Dec value, and, if the count value is less than the Thru value, the subthread reactivates the For Log Range output with the new iteration value.

A Break object operates. The subthread is deactivated and the sequence output pin is activated. Note that the value that remains on the For Log Range output is the same value present when the Break was encountered.

A Next object operates. The subthread is deactivated and the iteration counter is incremented by the /Dec value. If the count value is less than the Thru value, the subthread reactivates the Data output with the new iteration value, and execution of the subthread proceeds as usual. If the iteration counter has reached or exceeded the Thru value, the sequence output pin is activated. If the counter is exceeded, then the value that remains on the Data output is an out-of-range value.

When you add any of the optional data inputs, they do not necessarily line up with the names of the fields to which they supply a value. Make sure you know which values you are inputting and the pins associated with them. (Use Show Terminals if necessary.)

If the Thru value is less than From value, /Dec must be negative or the loop does not execute.

If /Dec = 0 the loop iterates infinitely or until a Break object is encountered in the subthread.

If From equals Thru, the loop executes once.

When the subthread hosted by the For Log Range object finishes an iteration, all data containers sent during the previous iteration are invalidated before the next iteration. This prevents "old" data from a previous iteration from being reused in the current iteration. However, if flow branching is present within the iterative subthread, some objects may not execute on every iteration. Thus, data containers sent by those objects may be invalidated before other objects can execute on the data. To obtain the desired propagation in this case, use the Sample & Hold object.

Location

Flow [image] Repeat [image] For Log Range

See Also

Break, For Count, For Range, Next, On Cycle, Sample & Hold, Properties (Object), Until Break, Properties (Object), and Object Menu

To Loop Part of a VEE Program


Formula

An object that performs a user-defined mathematical operation, function, or other expression specified by a mathematical formula.

Note
Refer to Function & Object Browser for information about the individual mathematical operations and functions supported by the Formula object.

Use

Use Formula to execute any desired mathematical expression supported by VEE. Many predefined operators and functions are available in the Function & Object Browser. Additionally, the browser displays user-defined functions, and ActiveX objects and controls that are available. The default Formula object has one input (A) and an example formula (2*A+3). However, the example can be replaced with any desired formula, and any number of inputs or outputs can be added as required by the user-defined formula. (If the formula requires no inputs, you may delete all inputs.)

The input(s) can be of any data type. For a relational formula (e.g. A <= B), the resulting output is a scalar Int32 with the value 0 ("false") or 1 ("true"). For other mathematical formulas, the resulting output is of a data type consistent with the inputs and with the formula itself. All nil inputs to formula objects, and to I/O transactions containing formulas are automatically converted to Real64 numbers with the value of 0.0. Refer to Understanding Data Containers for a discussion of the rules that determine the data type and shape of the result of a formula.

The outputs may be assigned values in the expressions. The Result output always contains the result of the last expression. Output terminals are essentially local variables to the Formula.

For a detailed discussion of expression syntax and math operations, refer to Tell Me About... Math Functions and Operations in Contents and Index under Help menu.

Open View Parameters

Formula field (unlabeled) - Default is 2*A+3. You can enter any mathematical formula consisting of the operators and functions located in the Function & Object Browser. After you enter a formula and click on another area of your program, the syntax is automatically checked and any errors are reported. The Formula field can be added as a control input, which accepts array and scalar text.

The Formula object expands to include multiple lines. With the edit cursor in the formula field, press the Enter key to move the cursor to a new line.

You can add comments between expressions as shown in this example:

c=2*a+3; // a comment to the end of line
d=sin(40); // another comment
// one last comment

Notes

All of the supported dyadic operators and functions are located in the Function & Object Browser. Any of these operators and functions, including calls to UserFunctions, Remote Functions, and Compiled Functions can be used in a Formula object to construct a mathematical expression using the described syntax. (The only exception is MATLAB functions, which can only be called from a MATLAB Script object.) If any ActiveX Controls or Automation objects are available for use in VEE, you can manipulate them in Formula expressions.

Although you could perform a series of mathematical calculations using several individual, predefined Formula objects, a single Formula object containing the same expressions will perform the same calculations with higher performance. This is because a fixed amount of overhead is associated with each graphical object in the program, so a program with fewer objects will run faster.

Multiple expressions can be entered on a single line, or on multiple lines. You can lay out the expressions in the Formula object in ways that are more readable. Use semicolons to separate expressions. You can split a single expression across multiple lines; however, do not split a variable name across two lines.

You can assign values to multiple outputs using multiple expressions. If a Formula object has outputs a, b, and c (as well as Result), the expressions:

a=2*3;
b=a+2;
c=a+b

result in the appropriate values being assigned to the three output terminals. Result will have the value of the last expression, in this case, c.

Output terminals may also be used for temporary storage in an expression. The following expressions swap values in an array, where the input a contains the array, and the output tmp is used for temporary storage:

tmp=a[2];
a[2]=a[3];
a[3]=tmp

The Formula object is a Rich Text Format box. The editing features in the Formula object include all of the features you would expect to find in an RTF box including:

Full arrow key functionality

Use of Delete, End, Home, Insert, Page Up and Page Down

Full 10 key support

Expression Evaluation Details

The following description about token search order applies to any expression whose evaluation is delayed until run time. These include expressions in various objects, such as Formula, If/Then/Else, and Set Values, and expressions in Sequencer and I/O transactions.

Since VEE can call UserFunctions (either locally created or imported from a library), Compiled Functions, or Remote Functions, it is possible to have two functions with the same name. Naming conflicts in an expression are resolved by searching tokens in the following order:

1. Local input/output terminals

2. Function names found in the same library as the calling object

3. Local UserFunctions

4. Built-in functions, such as sin()

5. Imported UserFunctions, Compiled Functions, and Remote Functions. The precedence between these three is not guaranteed. To ensure the desired selection, include the library name in the call, using “dot” notation. For example, myLib.func().

The precedence for resolving function names can cause unexpected results or errors if you are not careful to avoid conflicts. Consider this example:

At first glance, this formula appears to add the sine of 30 to the number on the input terminal, sending 2.5 as the result. However, terminal names have precedence over built-in function names (see above). The expression sin(30) will attempt to “call” the input terminal and treat it as a function or ActiveX method. If sin were an Object capable of evaluating sin(30), valid results are possible. However, it is more likely that these situations are a programming mistake or misunderstanding. In the example above, the result is a program failure with a confusing error message. This type of error is not limited to input pin names; it can happen any time two tokens have the same name and their precedence is not what you wanted. It is recommended that you avoid precedence problems by choosing unique names for all your variables and functions.

The search order described above applies to Execution Mode VEE 5 and higher. In earlier Execution Modes, variable and function names were searched in a different order. For example, in VEE 4 mode, internal function like sin() had top precedence. In VEE 5 mode (and higher), local UserFunctions were given precedence over internal functions, allowing the creation of customized versions of functions like sin(). This difference in search order can have a dramatic effect on programs containing similarly named functions from different libraries.

Location

Device [image] Formula

See Also

ActiveX Automation References, ActiveX Control References, Function & Object Browser, UserFunction,

Converting Data Types on Input Terminals, Code Completion, Code Insight, Execution Mode,

Processing Data (browse entire sequence), Understanding Data Containers (browse entire sequence),

To Enter a Formula, To Use Arrays or Array Elements in Expressions, Properties (Object),

To Use the Math Operators and Functions, To Use a Record in an Expression, and Object Menu.


For Range

An object that activates the data output a specified number of times.

Use

Use For Range to execute a subthread a specified number of iterations specified by a beginning value, ending value, and increment. Use For Range to generate values that are evenly distributed between the From and Thru values.

Open View Parameters

From - The beginning value of the iteration loop.

Thru - The ending value of the iteration loop. When the value of the iterator is greater than or equal to the Thru value, the loop is completed.

Step - The increment value between the current value of the iterator and its next value.

All open view parameters are available from data inputs.

Notes

The For Range output value is a Real64 scalar ranging from the From to the Thru value.

Execution of the subthread hosted by the For Range output continues until one of the following occurs:

All objects that can, have operated. The subthread is deactivated, the iteration counter is incremented by the step value, and, if the count value is less than the Thru value, the subthread is reactivated by refiring the For Range output with the new iteration value.

A Break object operates. The subthread is deactivated and the sequence output pin is activated. Note that the value that remains on the For Range output is the same value present when the Break was encountered.

A Next object operates. The subthread is deactivated and the iteration counter is incremented by the Step value. If the count value is less than the specified Thru, the subthread is reactivated by refiring the Data output with the new iteration value, and execution of the subthread proceeds as usual. If the iteration counter has reached the Thru value, the sequence output pin is activated.

When you add any of the optional data inputs, they do not necessarily line up with the names of the fields to which they supply a value. Make sure you know which values you are inputting and the pins associated with them. (Use Show Terminals if necessary.)

If the Thru value is less than the From value, Step must be negative, otherwise the output is never activated.

If Step = 0, the loop iterates infinitely or until a Break object is encountered on the subthread.

If From equals Thru, the loop executes once.

When the subthread hosted by the For Range object finishes an iteration, all data containers sent during the previous iteration are invalidated before the next iteration. This prevents "old" data from a previous iteration from being reused in the current iteration. However, if flow branching is present within the iterative subthread, some objects may not execute on every iteration. Thus, data containers sent by those objects may be invalidated before other objects can execute on the data. To obtain the desired propagation in this case, use the Sample & Hold object.

Location

Flow [image] Repeat [image] For Range

See Also

Break, For Count, For Log Range, Next, On Cycle, Sample & Hold, Properties (Object), Until Break, Properties (Object), and Object Menu

To Loop Part of a VEE Program


From

A menu item.

Use

Use From to access the following objects which are sources for I/O operations:

File

DataSet

String

Location

I/O [image] From

See Also

To


From DataSet

An object that allows the user to conditionally retrieve records from a data set.

Use

Use From DataSet to find and retrieve from a dataset either one record or all records that meet the constraints of a logical expression formula. If the record retrieved meets the constraints of the query expression, the record is output on the Rec output pin.

The default expression in the Formula field is 1, (true). Thus, either the first record found (One), or all records in the data set (All) will be output.

If you want to test values in record fields, you must use the form Rec.A for field A, Rec.B for field B, and so forth. For example, the expression:

Rec.A<10

tests each record to see if field A is less than ten. If Get records: One is specified, the first record in the dataset with field A less than 10 will be output on Rec. If Get records: All is specified, all records with field A less than 10 will be output. Note that the entire record will be output.

The following control pins may be added:

File Name - This control pin allows the user to change the name of the file from which the records will be read.

Rewind - This control pin "rewinds" the From DataSet file so that it can be re-read from the beginning of the file.

Formula - This control pin allows the user to change the formula which is used to determine which records read from the file will be output by the device.

Close - This control pin closes the file.

Open View Parameters

From DataSet - Click on the name field to display a dialog box, then select the name of the file that contains the DataSet.

Get Records - Select One or All:

If One is selected, the first record found in the data set that meets the constraints of the selection formula will be output, and From DataSet will stop executing. When One is selected, the output shape is always a scalar.

If All is selected, all records found in the data set that meet the constraints of the selection formula will be output. The output shape will always be an array. From DataSet will stop executing when it reaches the end of the file.

Search Specifier - Enter a mathematical expression to test the records in the data set. Either the first One, or All records that satisfy the expression will be output, depending on the Get Records selection. The default expression is 1 (true).

Notes

You may use any valid mathematical expression in the conditional formula. You may add additional inputs for use in the expression, just as for a Formula object. If you want to test values in record fields, express them as Rec.A, Rec.B, and so forth. The expression can be fairly complex, for example:

Rec.A > Rec.B AND Rec.C < 2.3

You must observe the normal stipulations for determining True or False for conditional expressions:

For any relational test (for example, equality between two operands), if one operand is an array, the other must be either a scalar or an array of the same size and shape. If the first operand is equal to the second, the result is True; otherwise it is False.

If both operands are of type Coord, they must have all of their independent variables and dependent variables match exactly for the result to be True. If independent variables do not match, an error is returned. Complex, PComplex, and Spectrum operands must have both parts match for the operation to return True. Enums are converted to Text for comparison.

Arrays must have all the respective values of both operands equal for the operation to return True.

You may wish to bring in a DataSet (an array of records) from a file, edit it, and then save it back to the file. This can be accomplished with a From DataSet, a Record Constant using the Default Value input pin, and a To DataSet. See Record Constant for more information.

You may add an EOF output pin to this object. When the object executes and there are no records meeting the query expression constraints, or you are already at the end of the DataSet, this pin will fire. Otherwise, an End of file with no Data Found error will result when this condition occurs.

If you have multiple From DataSet objects reading from the same file, they will share the file pointer. That is, all of the objects read sequentially through the file, no matter how many objects there are reading the file. See From File for more detail.

Location

I/O [image] From [image] DataSet

See Also

Build Record, Formula, Record Constant, To DataSet, UnBuild Record, Properties (Object), Object Menu, To Read Data from a File, and File Open Dialog Box.


From File

An object that reads data from a file using I/O transactions.

Use

Use From File object to read a wide variety of file encodings and formats. From File is especially useful for importing data files generated by other software packages.

When several From File objects refer to the same disc file, a single read pointer is maintained for all such objects even if they are in different threads or different contexts. This means that data read by one From File object is not reread by another From File object using the same file unless a REWIND operation has been done on the file. The file is opened and the file pointer is reset to the beginning of the file (implied REWIND) when the first From File object for that file operates after PreRun. All files are closed when the program stops.

From File Actions:

READ - Reads data from a file using the specified encoding and format.

EXECUTE - REWIND repositions the file's read pointer to the beginning of the file without erasing the contents of the file. CLOSE closes an open file. DELETE deletes the file.

WAIT - Waits the specified number of seconds before executing the next transaction.

From File Encodings:

TEXT - Reads text ASCII files written by VEE or other software packages.

BINARY - Reads all data types from a machine-specific binary format.

BINBLOCK - Reads all VEE data types from binary files with IEEE 488.2 definite length block headers.

CONTAINER - Reads all data types from a machine-specific text format.

Open View Parameters

Open View provides a field for the data file name, followed by a list of available transactions. The data file name can be added as a control input.

Open View shows the list of file transactions to be executed.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Notes

An EOF (End of File) output terminal can be added with Add Data Output. EOF is a special output terminal that propagates with a nil container when a transaction attempts to read data past the End of File. When an End of File condition is detected and the EOF output is activated, none of the other data outputs are activated, even if they contain newly read data.

If EOF is detected and there is no EOF output pin, an error is returned.

To read all of the data in the file, use a READ ... ARRAY TO END: transaction.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

I/O [image] From [image] File

See Also

To File, To Read Data from a File, Properties (Object), Object Menu, File Open Dialog Box, and To Edit a Transaction


From String

An object that reads data from a string by using transactions.

Use

Use From String to read a wide variety of encodings and formats from textual data in a string.

If a one-dimension array of Text is passed to the AString input, the From String transactions will act in the same way as if those lines of text were being read from a file with the From File object. That is, an array of Text will be treated as a single stream of text with new-line characters between each string element.

From String Actions:

READ - Reads data using the specified encoding and format.

WAIT - Waits the specified number of seconds before executing the next transaction.

From String Encodings:

TEXT - Reads all data types from the AString input.

CONTAINER - Reads all data types from a VEE specific text format.

Open View Parameters

The open view shows the list of transactions to be executed.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Notes

From String is a useful debug tool to explore how READ TEXT transactions operate. Connect a Text Constant object to the From String input terminal labeled AString, and connect a Logging AlphaNumeric display to the From String output terminal to immediately view the results. It's also useful to parse a string returned from an instrument.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

I/O [image] From [image] String

See Also

From, From File, To String, Properties (Object), Object Menu, To Convert a String into a Number, and To Edit a Transaction


Function & Object Browser

A Device menu item for accessing mathematical and logical functions, ActiveX Objects, Agilent VEE objects, etc.

Use

Use Function & Object Browser to access the Functions and Objects in Agilent VEE. From the browser, you can choose from:

Operators

Built-in Functions

MATLAB Functions

Local UserFunctions

Imported UserFunctions

Remote Functions

Compiled Functions

ActiveX Objects

.NET/CLR Objects

VEE Objects

Instruments

Window Information

The Function & Object Browser Tool window contains a toolbar and three panes: the Types pane, the Members pane, and the Description pane. The Types pane displays in the left side of the Function & Object Browser, the Members pane displays on the top of the right side, and the Description pane displays at the bottom of the right side.

Types pane

Types pane contains all types of functions and objects you can browser. They are Operators and Built-in Functions, MATLAB Functions provided with VEE, Local, Imported, Remote and Compiled Functions created by the user, ActiveX Objects, VEE Objects, .NET/CLR Objects, and Instruments.

The contents of the Types pane display in a tree view. When you expand a Type by double-clicking it or by clicking the plus sign (+) next to its name, the sub types appear.

For ActiveX Object, you can expand it to library names currently referenced and then expand to classes included in that selected library. Select a class name to display the properties, methods, and events that are available for an ActiveX object in the Member pane.

For .NET/CLR Object, you can expand it to assemblies, which are the reusable, versionable, self-describing building blocks of .NET applications. Assemblies can be expanded to Namespaces. Select a namespace to see a partial listing of the members that are available within that namespace in the Member pane.

Member pane

If Operators or any function names are selected in Type pane, Member pane lists the names of operators and functions available in the selected Type. A scroll bar is provided for lists that are larger than the provided space. To get an operator or function from this list to put in a program, click on the Member name and click Create Formula button [image] , or simply double-click on the name.

If ActiveX Objects is selected in Type pane, the Member pane contains the properties, methods, and events available for an ActiveX object that are related to the selected Library and Class names. To create formulas in a program for properties and methods, click on the property or method name and click Create Get Formula button [image] on the Toolbar or double-click on the name.

If .NET/CLR is selected in Type pane, the Member pane contains constructors, properties, methods, and enumerators available for the .NET/CLR object selected in Type pane. To create formulas in a program for properties and methods, click on the property or method name and click Create Get Formula button on the Toolbar or double-click on the name.

You cannot create anything from the event names. To create event handlers for an ActiveX automation object, declare a variable of type Object using Declare Variable, enable its events, then use Create Event Handler in the object menu. To create event handlers for an ActiveX control, you must add the control to your program first (Device ActiveX Controls), then use Create Event Handler in the object menu.

Description pane

The pane displays detailed information of names selected in Member pane.

For built in functions, VEE provides a description string for the highlighted function. For local, imported, and remote functions, VEE displays the contents of the Show Description dialog box for the highlighted function. For ActiveX objects, VEE displays the formula syntax with parameters.

For additional information on any of the names in the Member pane, highlight a name and click Help toolbar button or press F1. The information about Operators and Built-in Functions is available from VEE Help. Information about ActiveX Members is available if vendors have supplied online help for them.

Toolbar

The Function & Object Browser toolbar allows you to

  • Creates a formula for the selected Operator, Built-in function, MATLAB function, member function of ActiveX object, or member function of .NET/CLR object.

  • Creates a Set formula for the selected ActiveX object's property, .NET/CLR object's property, Agilent VEE object's programmatic property, or Instrument's property.

  • Creates a Get formula for the selected ActiveX object's property, .NET/CLR object's property, Agilent VEE object's programmatic property, or Instrument's property.

  • Creates a Call for the selected Local, Imported, Remote UserFunction, or Complied function.

  • Creates a Call for the selected UserFunction.

  • Creates a Event Handler for the selected event.

  • Allows you to create .NET operations for the selected .NET object.

  • Copies the selected member to the clipboard. You can paste it as text to an editor window.

  • Collapse all items in the Type pane.

  • Opens the online help topic for the selected member.

Right click an item in the Member pane opens the context menu of that item. The context menu includes the same commands as the toolbar.

Double click an item in the Member pane automatically creates an VEE object for that item. The type of the VEE object created varies according to the type of the item selected.

Location

Device [image] Function & Object Browser

See Also

ActiveX Automation References, ActiveX Control Host, ActiveX Control References, ActiveX Controls, Assignment, Call, Declare Variable, Delete Library, Edit UserFunction, Import Library, Miscellaneous Operators, and UserFunction.

To Use the Math Operators and Functions


Function Generator

An object that outputs a Waveform.

Use

Use Function Generator to generate a Waveform of your own specifications.

Properties

ErrorOnAliasing - Evaluates whether Num Points divided by Time Span (same frequency) is less than twice the specified frequency. If it is, an error is returned. The purpose of this evaluation is to determine whether the points being generated provide an accurate representation of the function being generated. A selected check box generates a literal presentation of points. Default is on.

Open View Parameters

All of these parameters may be set from the open view or added as data inputs.

Function - The shape of the waveform (Sine, Square, Triangle, and so forth). Default is Cosine.

Frequency - The frequency of the waveform in Hertz. This parameter is ignored if the Function is set to DcOnly. Default is 200 Hertz.

Amplitude - The absolute value of the maximum and minimum values in linear units before any dcOffset is added. Default is 1.

dcOffset - The offset of the waveform (the amount it is shifted up or down). Default is 0.

Phase Units - Degrees (Deg), radians (Rad), or gradians (Grad). Phase Units overrides the current Trig Mode for the phase value. Default is Deg.

Phase - The shift of the waveform by a portion of a period. The waveform is shifted toward negative time for positive values of phase. Phase is ignored when Function is set to DcOnly. Default is 0.

Time Span - The duration of the waveform (in seconds). Default is 20m seconds.

Num Points - The number of points in the waveform. The time between points in the waveform is Time Span/Num Points. Num Points must be positive. Default is 256.

Notes

There are the same number of points as sampling intervals. Each point is at the beginning of the sampling interval.

Location

Device [image] Virtual Source [image] Function Generator

See Also

Build Arb Waveform, Comparator, Noise Generator, Pulse Generator, and Object Menu


Gate

An object that passes the input data to the data output pin when the sequence in pin is activated.

Use

Use Gate to hold the container until another action occurs (and activates the sequence input pin).

Notes

If the sequence input pin is not connected, there is no "holdoff" effect. Therefore, Gate passes the data from data input pin to data output pin whenever the data input pin is activated.

The data that flows into Gate is not stored; the container on the data input pin is the container output when the sequence input pin is activated.

Location

Flow [image] Gate

See Also

DeMultiplexer, JCT, Properties (Object), and Object Menu

To Output a Value on Timeout


Get Current Directory

Retrieves the current directory on the host machine.

Location

System [image] Directory [image] Get Current Directory


Get Directory Name

Retrieves the directory name of the provided path.

Location

System [image] Path [image] Get Directory Name


Get Extension

Retrieves the file name extension. For example, the file test1.xls would return the extension xls.

Location

System [image] Path [image] Get Extension


Get Field

An object that allows the user to unbuild a record and recover one of its fields or sub-fields.

Use

Use Get Field to extract a field or sub-field of a record. The Get Field object is simply a Formula object that is initialized with an input terminal Rec and the expression Rec.A. Use the "dot" syntax to specify the field that you want to extract from the record input. For example, Rec.A extracts the A field from the Rec record input.

Open View Parameters

Formula field (unlabeled) - The default is Rec.A. You can enter any mathematical formula allowed in the Formula object, but normally you would want to use the A.B dot syntax to extract a field from a record. You can add a Formula control input.

Notes

The Get Field object is actually just a Formula object that has been initialized with a Rec input and the expression Rec.A. You can use any expression in Get Field that you can use in a Formula object, but to extract a field you will need to use the "dot" syntax like Rec.A or A.B.C.

The A.B dot syntax in Get Field is fully supported in all Formula objects. These include Formula, If/Then/Else, Get Values, Set Field, and all transaction devices (To File, To String, etc.)

Note the distinction between the Get Field, UnBuild Record, and SubRecord objects.

The Get Field object works like a Formula object, in that it uses dot syntax (A.B) to unbuild a record. Note that Get Field allows you to unbuild a record of records in one step by using an expression such as A.B.C. This process would require two UnBuild Record objects.

The UnBuild Record object has outputs for the Name List and Type List of the input record fields. The other (optional) outputs A, B, etc. of the UnBuild Record object return the same results as would multiple Get Field objects.

The SubRecord object differs from UnBuild Record and Get Field in that its output is always a record. The SubRecord device allows you to either include or exclude a list of fields from a record to form a subrecord.

Location

Data [image] Access Record [image] Get Field

See Also

Build Record, Formula, Record Constant, Set Field, SubRecord, and UnBuild Record.

To Extract a Field from a Record


Get File Creation Time

Retrieves the creation time of the file at the specified path.

Location

System [image] File [image] Get File Creation Time


Get File Name

Retrieves the file name from the provided path.

Location

System [image] Path [image] Get File Name


Get File Name Without Extension

Retrieves the file name of the file given in the path but excludes the file extension.

Location

System [image] Path [image] Get File Name Without Extension


Get Full Path

Retrieves the full path to file using the current directory as a starting point. For example, you are in the temp directory. There is a directory named test in your temp directory and in the test directory is a file named balderdash. When you use this object to search for the file balderdash, the temp directory tree is searched and the full path to the file is returned.

Location

System [image] Path [image] Get Full Path


Get Files

Retrieves the files in a directory in the input path and displays them in a one-dimensional array.

Location

System [image] Directory [image] Get Files


Get Last File Access Time

Retrieves the time of the last file access for the given file.

Location

System [image] File [image] Get Last File Access Time


Get Last File Write Time

Retrieves the time of the last file write for the given file.

Location

System [image] File [image] Get Last File Write Time


Get Logical Drives

Retrieves a one-dimensional array of logical drives on the host system.

Location

System [image] Directory [image] Get Logical Drives


Get Mappings

An object that outputs mapping information about a container.

Use

Use Get Mappings to get information about mapped arrays. Get Mappings outputs the type of mapping (log or linear) and the beginning and ending values of each mapping for each dimension.

Open View Parameters

NumDims - The number of dimensions in the input array, which is an integer value with a minimum value of 1 and a maximum value of 10.

Notes

If the input array is not mapped, Get Mapping outputs Linear (0,n-1), where "n" is the number of points in that dimension of the input array.

Get Mapping does not allow a Coord as input, because the Coord data type has explicit mappings.

Num Dims must match the number of dimensions in the input array.

If the Num Dims value is changed, the view automatically creates or deletes output terminals so that the number of outputs, three for each dimension, matches the value of the Num Dims value. For each dimension, Get Mappings has three data output terminals.

Short Cuts

To view the mappings of a mapped array, use Line Probe on a line or open the terminal to view the container data.

Location

Data [image] Access Array [image] Get Mappings

See Also

Line Probe, Set Mappings, Properties (Object), UnBuild Data, and Properties (Object)


Get Parent Directory

Retrieves the path of the parent directory.

Location

System [image] Directory [image] Get Parent Directory


Get Path Root

Retrieves the root of any path passed to it.

Location

System [image] Path [image] Get Path Root


Get Root Directory

Retrieves the root directory of the host system for the current VEE session.

Location

System [image] Directory [image] Get Root Directory


Get Specified Files

You provide a path and a wildcard pattern (for example, *.vee). This object then retrieves files matching that pattern.

Location

System [image] Directory [image] Get Specific Files


Get Subdirectories

Retrieves a one-dimensional array of sub-directories. This is not a recursive listing. It is the first level of sub-directories below the directory specified in the path parameter.

Location

System [image] Directory [image] Get Subdirectories


Get Temp Directory Path

Retrieves the path to the temporary directory. This is usually C:\Documents and Settings\{UserName}\Local Settings\Temp\.

Location

System [image] Path [image] Get Temp Directory Path


Get Temp File Name

Creates a temporary file in C:\Documents and Settings\{UserName}\Local Settings\Temp. It then retrieves the file name.

Location

System [image] Path [image] Get Temp File Name


Get Values

An object that extracts elements from an array.

Use

Use Get Values to access particular elements of an array. You can extract single or multiple elements, columns, or rows from one or more arrays.

Use Get Values to get information about a set of data such as: the data type, the number of dimensions, the dimension sizes, and the total size of all the array elements of the input array.

Open View Parameters

Formula field (unlabeled) - Specifies the elements of the array that you are extracting. The specific symbols associated with arrays are:

Comma (,) - Separates element dimensions.

Colon (:) - Indicates a set of elements inclusively.

Asterisk (*) - A wild card to indicate the entire column or row.

Example

To extract the 2nd column from a two dimensional array [3,3] elements, keeping in mind that array indices are zero-based:

- - - -
|1 2 3 |                      | 2 |
|4 5 6 | Array [*,1] outputs: | 5 |
|7 8 9 |                      | 8 |
- - - -

Notes

All arrays are zero-based.

There must be exactly one specification for each array dimension.

The Get Values object is actually just a Formula object that has been initialized with an Ary input, the expression Ary, and several outputs. You can use any expression in Get Values that you can use in a Formula object.

The Ary[2,3] subarray syntax in Get Values is fully supported in all Formula objects. These include Formula, If/Then/Else, Get Field, Set Field, and all transaction devices (To File, To String, etc.).

The data type string output value is the same as the string returned from the typeName() function.

Location

Data [image] Access Array [image] Get Values

See Also

Array, Formula, Set Values, typeName(), UnBuild Data, and Properties (Object)

To Extract Values from an Array


Get Variable

An object that gets the value of a variable that has already been created in the execution of the current program.

Use

Use the Get Variable object to get a variable (by name), for use as data in a VEE program. The variable must have been previously created or initialized by a Set Variable or Formula assignment object within the program.

Undeclared Global Variables created (with Set Variable) in one context of a program can be used as data in another context of that program such as UserObjects and UserFunctions. For example, a Set Variable in the root context of a program could create an undeclared global variable, which could then be used as data by including a Get Variable in a UserObject. This is especially useful when the program contains several nested layers of UserObjects.

Variables may also be used by name in the expression fields of the following objects: Formula, If/Then/Else, Get Values, Get Field, Set Field, and all objects using expressions in transactions, including To File, From File, Direct I/O, From Stdin, and Sequencer. This direct usage is often more useful than the Get Variable object.

Open View Parameters

The open view displays a field for the name of the variable. The name is not case sensitive (either lower-case or upper-case letters may be used). Thus globalA is the same variable as GLOBALa. The name field may be added as a control input. The name can only be the name of the variable, it cannot be an expression such as globalA+1 or globalRec.field. Use expressions such as these in a Formula.

Notes

To avoid unexpected results, your program must ensure that a variable is set with Set Variable before a Get Variable object (or an object that includes the variable name in an expression) executes. Generally, the best way to ensure this is to connect the sequence output pin of the Set Variable object to the sequence input pin of the Get Variable object, or other object that uses the variable. However, there are cases when the sequence input pin need not be connected. For further information about this, refer to "Variables" in VEE Advanced Techniques.

In Default Preferences, if Delete Variables at PreRun is on (the default), all variables are deleted before your program executes. If Delete Variables at PreRun is turned off, variables will not be deleted, and you must program carefully to avoid propagating invalid data.

Global variables are truly global since they are not defined at a UserObject level. A global variable that is defined in one context of a program can be used in any other context within the program. For example, you can define a global variable with a Set Variable object in the root context of the program, and then include a Get Variable to get that global variable in a UserObject. However, you will need to avoid name conflicts throughout the program:

If two or more Set Variable objects attempt to set the same variable (with the same name), the current value will be overwritten as each Set Variable executes. This may result in unexpected behavior if you are unaware of the duplicate names.

If there is a data terminal variable with the same name as a variable, the data terminal variable takes precedence.

For further information, refer to Help => Contents and Index => Tell Me About... => Variables.

Location

Data [image] Variable [image] Get Variable

See Also

Default Preferences, Delete Variable, Set Variable, To Use a Variable, and Properties (Object).


Has Extension?

Retrieves a boolean value if the file in the provided path has a file name extension. For example, in the file test.xls, xls is the file name extension and a boolean true would be returned.

Location

System [image] Path [image] Has Extension?


Hash Table - Add Key/Value Pair

Add the key/value pair to the hash table.

Location

System [image] Collections [image] Hashtable [image] Add Key/Value Pair


Hash Table - Clear

Clears the hash table.

Location

System [image] Collections [image] Hashtable [image] Clear Hashtable


Hash Table - Contains Key?

Does the given hash table contain the given key.

Location

System [image] Collections [image] Hashtable [image] Contains Key?


Hash Table - Count

Provides a count of the number of key/value pairs in the hash table.

Location

System [image] Collections [image] Hashtable [image] Count


Hash Table - Create

Creates a new hash table.

Location

System [image] Collections [image] Hashtable [image] Create


Hash Table - Enumerate Key/Value Pairs

Lists the key/value pairs of the given hash table.

Location

System [image] Collections [image] Hashtable [image] Enumerate Key/Value Pairs


Hash Table - Get Value

Gets the hash value given the hash table and hash key.

Location

System [image] Collections [image] Hashtable [image] Get Value


Hash Table - Remove Key/Value Pair

Removes a key/value pair from a hash table.

Location

System [image] Collections [image] Hashtable [image] Remove Key/Value Pair


Hash Table - Set Value

Sets a value for a given key in a given hash table.

Location

System [image] Collections [image] Hashtable [image] Set Value


Help (Object Menu)

Gives help on this object.

Use

Use Help to view the reference page for this object. To exit help, close the help window.

Notes

To get help on multiple objects, terminology, or procedural information, use the Help menu on the VEE menu bar.

Help for Instrument Panel or Component Driver contains help about the driver itself.

Shortcut

To get help quickly on a selected object, press F1.

Location

On each object menu [image] Help

See Also

Object Menu and Properties (Object).


Home

Move the upper left corner of the program to the upper left corner of the work area (Main, UserFunctions, or UserObjects).

Shortcuts

Press [image] button on Toolbar, or click Home key.

Location

Edit [image] Home

See Also

To Navigate Programs


Horizontal Paddle

See Toggle Control.


Horizontal Rocker

See Toggle Control.


Horizontal Slide

See Toggle Control.


If A ~= B

An object that branches output if the data input values are almost equal.

Use

Use If A ~= B to test for approximate equality and branch based on that test.

Notes

If A ~= B is a pre-configured If/Then/Else object that tests the approximate equality of the inputs.

If the inputs are approximately equal, the Then output is propagated with an Int32 scalar 1, else the Else output is propagated with an Int32 scalar 0.

The test for "almost equal" is slightly different for Complex and Polar Complex numbers. For two real numbers (a and b) the test for "almost equal" is:

a - b <= a * 10E-7

However, for two Complex values (a and b) the test is:

re(a) - re(b) <= mag(a) * 10E-7

where:

re(a) is the real component of a

re(b) is the real component of b

mag(a) is the vector magnitude of a

Location

Flow [image] Conditional [image] If A ~= B

See Also

Comparison, Conditional, If/Then/Else, If A == B, If A != B, If A < B, If A > B, If A <= B, and If A >= B.

To Branch within a VEE Program


If A == B

An object that branches output if the data input values are equal.

Use

Use If A == B to test for equality and branch based on that test.

Notes

If A == B is a pre-configured If/Then/Else object that tests the equality of the inputs.

If the inputs are equal, the Then output is propagated with an Int32 scalar 1, else the Else output is propagated with an Int32 scalar 0.

Location

Flow [image] Conditional [image] If A == B

See Also

Comparison, Conditional, If/Then/Else, If A ~= B, If A != B, If A < B, If A > B, If A <= B, and If A >= B.

To Branch within a VEE Program


If A >= B

An object that branches output if one input is greater than or equal to the other.

Use

Use If A >= B to test for one input being greater than or equal to the other, and branch based on that test.

Notes

If A >= B is a pre-configured If/Then/Else object.

If the value of A is greater than or equal to the value of B, the Then output is propagated with an Int32 scalar 1, else the Else output is propagated with an Int32 scalar 0.

Location

Flow [image] Conditional [image] If A >= B

See Also

Comparison, Conditional, If/Then/Else, If A ~= B, If A == B, If A != B, If A < B, If A > B, and If A <= B.

To Branch within a VEE Program


If A > B

An object that branches output if one input is greater than the other.

Use

Use If A > B to test for one input being greater than the other and branch based on that test.

Notes

If A > B is a pre-configured If/Then/Else object.

If the value of A is greater than the value of B, the Then output is propagated with an Int32 scalar 1, else the Else output is propagated with an Int32 scalar 0.

Location

Flow [image] Conditional [image] If A > B

See Also

Comparison, Conditional, If/Then/Else, If A ~= B, If A == B, If A != B, If A < B, If A <= B, and If A >= B.

To Branch within a VEE Program


If A <= B

An object that branches output if one input is less than or equal to the other.

Use

Use If A <= B to test for one input being less than or equal to the other, and branch based on that test.

Notes

If A <= B is a pre-configured If/Then/Else object which tests for the inequality of the inputs.

If the value of A is less than or equal to the value of B, the Then output is propagated with an Int32 scalar 1, else the Else output is propagated with an Int32 scalar 0.

Location

Flow [image] Conditional [image] If A <= B

See Also

Comparison, Conditional, If/Then/Else, If A ~= B, If A == B, If A != B, If A < B, If A > B, and If A >= B.

To Branch within a VEE Program


If A < B

An object that branches output if one input is less than the other.

Use

Use If A < B to test for one input being less than the other, and branch based on that test.

Notes

If A < B is a pre-configured If/Then/Else object.

If the value of A is less than the value of B, the Then output is propagated with an Int32 scalar 1, else the Else output is propagated with an Int32 scalar 0.

Location

Flow [image] Conditional [image] If A < B

See Also

Comparison, Conditional, If/Then/Else, If A ~= B, If A == B, If A != B, If A > B, If A <= B, and If A >= B.

To Branch within a VEE Program


If A != B

An object that branches output if the inputs are not equal.

Use

Use If A != B to test for inequality and branch based on that test.

Notes

If A != B is a pre-configured If/Then/Else object which tests for the inequality of the inputs.

If the value of A is not equal to the value of B, the Then output is propagated with an Int32 scalar 1, else the Else output is propagated with an Int32 scalar 0.

Location

Flow [image] Conditional [image] If A != B

See Also

Comparison, Conditional, If/Then/Else, If A ~= B, If A == B, If A < B, If A > B, If A <= B, and If A >= B.

To Branch within a VEE Program


If/Then/Else

An object that branches execution flow based on the values of its input(s).

Use

Use If/Then/Else to make decisions about which subthread branch to execute. You may enter any legal math expression in the formula boxes on the open view.

Only the output pin associated with a true condition is activated. The container output is the value of the expression.

If/Then/Else evaluates the expressions in the If/Else If clauses (top to bottom) until one evaluates to a non-zero value. This non-zero container is copied to that expression's corresponding output and that one output is propagated. Only one output is propagated. If none of the expressions evaluate to a non-zero value, then the Else output is propagated with the zero value of the last evaluated expression.

If any of the expressions evaluate to a value that is an array, the array values are checked to see if they are either all zero or all non-zero. If the values are mixed, an error is returned since it cannot be determined whether the array is true or false. To produce a scalar, use expr == 0 or expr!=0 since the equality comparisons always return a scalar.

Open View Parameters

Enter an expression in the edit field.

Object Menu

Add Else/If - Adds a condition that is tested if the previous condition is not met and an output pin that is activated if the condition is true. The new condition is added below all current conditions.

Insert Else/If - Opens a dialog box listing the current conditions, letting you insert a new condition (and related output pin) before any of the current ones.

Delete Else/If - Deletes a condition. After selecting Delete Else/If, select a condition to delete from a dialog box that is displayed.

Delete Else/If is not available when only one condition is displayed. This feature is only available if you have at least two Else/If conditions.

Notes

You may use any legal mathematical statements in the conditional statement. You may add additional inputs for use in the expressions, just as in the Formula object.

To output a value when it meets a condition, multiply the condition statement by the value. For example, to output the value in the variable A when A is less than 10, use the following expression in the edit field:

(A<10)*A

When this condition is true, the value of A is output on the Then data output pin. This technique works only for true statements (which output to Then or Else If data output pins). Also, this technique only works when A does not equal 0. If A equaled 0, the result of the equation would be false and zero would be output on the Else data output pin. The Else data output pin will always return zero if the condition is false.

The objects under Flow [image] Conditional are pre-configured If/Then/Else objects that test for a specific condition.

To get a TRUE|FALSE (1|0) output, use the Comparison objects. They are available in the Function & Object Browser under Operators => Comparison.

Also note the difference between Comparison and Conditional objects. Comparisons are formulas with output 0 or 1. Conditionals are If/Then/Else and have two outputs, of which one activates.

Location

Flow [image] If/Then/Else

See Also

Comparison, Conditional, Formula, Triadic Operator, Properties (Object), and Object Menu

To Branch within a VEE Program


Import Library

An object that loads a library of UserFunctions, Compiled Function definitions, or Remote Function definitions into a running VEE program.

Use

Use Import Library to load a library of one of the following kinds of functions into your VEE program at run time:

UserFunction - Import Library loads all of the UserFunctions from a specified file. (UserFunctions are created by selecting the Make UserFunction selection on the object menu of a UserObject. You create a library by creating several UserFunctions and saving them to a file.)

Compiled Function - Import Library attaches a Dynamically Linked Library, or DLL to the VEE process, and parses the Definition File declarations. (Compiled Functions are programs written in a programming language such as C, which are dynamically linked to the VEE process.

Remote Function - Import Library starts a VEE process on a remote host and loads the Remote File into the VEE process. (Remote Functions are actually UserFunctions loaded by the remote VEE process, but callable on the local host.)

Once the library of UserFunctions, Compiled Functions, or Remote Functions is loaded, the functions are executed (called) by name using the Call Function object.

Open View Parameters

Library Type - A dialog box allows you to choose UserFunction, Compiled Function, or Remote Function.

Library Name - Assign a logical name to the library you are loading.

File Name - (UserFunction or Compiled Function only.) Select the file that contains the library to import. For Compiled Functions this is a .dll.

Definition File - (Compiled Function only.) Select the definition file for the Compiled Function. This is the file containing the prototypes for the function calls (the .h file).

Host Name - (Remote Function only.) Enter the name of the remote host where the Remote Function will operate.

Remote File Name - (Remote Function only.) Enter the file name (complete path) of the library (e.g. /users/MyUserName/MyDir/MyFile).

Remote Timeout - (Remote Function only.) Set the timeout in seconds for the Remote Function.

Geometry - (Remote Function only.) Enter the initial geometry for the window that contains the view of the remote VEE, in the standard geometry format. For example, 800x500+0-0 (width x height+/-xoffest+/-yoffset.

Remote Debug - (Remote Function only.) When this checkbox is selected, all of the UserFunctions within the library will execute in debug mode (i.e. you will be able to perform debugging on them such as setting breakpoints and doing line probes). The program will pause just before executing each remote UserFunction. This setting works with UserFunctions whether or not they have panel views.

Object Menu

Load Lib - Immediately loads the specified library into VEE. If a library with the same name was previously loaded, that library is deleted and overwritten with the new library.

Delete Lib - Immediately deletes the specified library from VEE. (This provides the same functionality as the Delete Library object.)

Notes

The Import Library object is generally used for advanced operations where you have developed sets of UserFunctions, Compiled Functions, or Remote Functions into libraries. Import Library allows you to load such libraries dynamically at run time. For UserFunctions you can save considerable space by creating a library and loading it with Import Library -- you don't have to save copies of the UserFunctions in each individual program. Also, when you develop a library of standard UserFunctions, you can keep the source code for those functions in a single place.

UserFunctions loaded at run time by Import Library operate exactly like any locally-created UserFunction within the program. You can execute any UserFunction with the Call Function or Formula object. However, only locally created UserFunctions can be edited within the program. Imported UserFunctions cannot be edited, but they may be viewed for debugging purposes using Edit UserFunction. If you want to edit any of the external UserFunctions, you must open the library file that contains the UserFunctions and use the Edit UserFunctions selection on the Edit menu. Once you have edited the UserFunction, save the file back to the disk.

Doing an Import Library from a program file containing an embedded I/O configuration does not import any of that I/O configuration. See Embedded I/O Configurations and Merging.

Location

Device [image] Import Library

See Also

Call, Delete Library, Edit UserFunction, UserFunction, UserObject, Properties (Object),Using a Compiled Function, Building a C Function, Creating a Dynamic Link Library, and File Open Dialog Box.


Indicator

This menu choice offers you a variety of analog-type graphical displays based on Scalar numeric input values.

Use

The Indicator menu provides you with a choice of five different VEE objects for graphical display of Scalar numeric input values. These five objects are:

Meter - Displays Scalar numeric values on an analog-type meter scale.

Thermometer - Displays Scalar numeric values using a color bar inside a graphical thermometer.

Fill Bar - Displays Scalar numeric values graphically using a color bar.

Tank - Displays Scalar numeric values graphically using a color bar inside a graphical tank.

Color Alarm - A graphical alarm indicator that displays different colors and text strings, depending on the Scalar input value.

Location

Display [image] Indicator

See Also

Color Alarm, Fill Bar, Meter, Tank, and Thermometer.

To Show a Color Alarm

To Show an Analog Display of Data


Instrument Event

An object that captures events generated by GPIB, USB, TCPIP, Serial, or VXI devices.

Use

The Instrument Event object can be configured to detect various device events. Depending upon configuration, the object may wait for the event, giving up execution to other parallel threads, or it may simply return a boolean (0 or 1) or other indicator of the state of the device.

If the Instrument Event object has been configured to wait for the event, then upon the event the object will execute. Any thread hosted by this object will have priority over any other parallel threads, and will execute to completion. If the Instrument Event object has been configured to simply return an indicator of device state, the thread containing it will have normal priority, and will execute in parallel with any other threads.

Open View Parameters

Device - The currently selected device is displayed in the Device field. Click on this field to display a list of the currently configured GPIB, USB, TCPIP, Serial, and VXI devices.

Event - Allows selection of specific events. Click on this field to display the choices:

Spoll - Returns the status byte of GPIB, USB, TCPIP, Serial devices and VXI devices. If a Serial device has been selected, the only possible selection is Spoll. The returned status byte is used with the Mask value. Spoll is not a real asynchronous event even when the Any Set or All Clear action is chosen. Spoll object reads the status byte and evaluates it continuously with the Mask value until the correct bits are modified by the device.

RQS - Returns the status byte of VISA-only GPIB, USB, and TCPIP devices. The returned status byte is used with the Mask value. RQS is a true asynchronous event. It waits until interrupt occurs and the status byte satisfies the Any Set or All Clear criteria.

SRQ - For VXI, an SRQ is generated from a message-based device when the device sends either a VME interrupt or a signal register write that is a request-true event. When this asynchronous event occurs, the device's status byte is returned, thus causing the device to generate a request-false event. The returned status byte is used with the Mask value.

Signal Interrupt - This asynchronous event is generated from either message-based or register-based VXI devices. The event occurs when the device sends either a VME interrupt or a signal register write that is a device-defined event or an undefined event. The returned 32-bit value is the value placed in the signal write register, or the value placed on the VXI Bus when the device does an interrupt acknowledge (IACK). This value is used with the Mask value.

Refer to Notes for detailed information about Event.

Action - Determines the execution behavior of the Device Event object upon detection of the specified event, in conjunction with the specified bit mask.

No Wait - Execute immediately, outputting the current state of the configured event, as specified by a 32-bit integer, to the status pin. This value is either the boolean value FALSE (0) or a device-dependent bit pattern. If the event choice is Spoll, the low byte of the returned integer is the status byte of the device. For the two asynchronous VXI events, a FALSE (0) is returned if the event has not occurred. If the event has occurred, the device-dependent bit pattern is returned.

All Clear - Wait for the event to occur and use the returned value in a logical AND operation with the Mask value. If no bit is set, then execute by placing the original, unmasked value on the status output pin.

Any Set - Wait for the event to occur and use the returned value in a logical AND operation with the Mask value. If any bit is set in the resulting bit pattern, then execute by placing the original, unmasked value on the status output pin.

Mask - You can enter a value to be used as a bit mask (default = 0). The Mask value is used in a logical AND operation with the value returned by the device when the specified event occurs.

Notes

The execution behavior of the Instrument Event object can either be asynchronous or synchronous as determined by the choice of the Action parameter. No Wait specifies a synchronous, polling behavior. The object executes immediately and any attached thread will have the same priority as all other threads currently executing. Choosing Any Set or All Clear causes the Device Event object to wait until both the event has occurred, and the logical AND of the Mask value and the value returned by the device satisfies the "any bit set" or "no bit set" criteria. When both of these conditions have been satisfied, the object executes. Any thread attached will have a higher priority, and will execute to completion, blocking all other concurrently executing threads.

Strictly speaking, the Spoll event is not a true asynchronous event as are the RQS, VXI SRQ and Signal Interrupt. By using a Mask value and the appropriate action, Any Set or All Clear, the status byte can be read and evaluated continuously with the Mask value until the correct bits are modified by the device. The object will wait until this occurs, allowing concurrent threads to continue execution. For the Spoll event, choosing the No Wait Action is identical to specifying the All Clear Action with a mask value of zero -- the Device Event object executes immediately.

For the true asynchronous events RQS, SRQ and Signal Interrupt, the device waits until the event occurs, allowing concurrent threads to continue executing. Once the interrupt occurs, the status byte, resulting status byte, signal write register contents, or IACK value will be logically ANDed with the mask value. The object executes only if the resulting bit pattern satisfies the Any Set or All Clear criteria. If the All Clear action is specified with a mask value of zero, the Device Event object will execute when the interrupt occurs.

A control pin is available as an input to programmatically change the device timeout period.

Location

I/0 [image] Advanced I/O [image] Instrument Event

See Also

Interface Event, Interface Operations, and Properties (Object)

To Poll GPIB Instruments


Instrument Manager

Displays the Instrument Manager tool window.

Use

Select I/O [image] Instrument Manager to display the Instrument Manager tool window. Use this tool window to add, delete, edit, and configure interfaces and instruments. You can also create the following types of instrument I/O objects: Direct I/O, IVI-COM Drivers, NIDAQ Drivers, VXIplug&play Drivers, Panel Drivers, and Component Drivers.

Window Information

The Instrument Manager tool window contains an Instrument pane and a toolbar:

Toolbar

The Instrument Manager toolbar allows you to find and add instruments, load sample programs, save and print IO configuration file, restore to saved I/O configuration, open help topics, and create I/O objects.

Find Instruments: This button starts an automatic search for all instruments available on the selected interface. If the root node is selected, all local interfaces are searched for instruments. The Auto Discovery Settings dialog (displayed by clicking the Settings… button) controls some details of this search.

From version 8.0, VEE starts to phase out older inconsistent I/O devices (mixed SICL & VISA) for a more uniform approach (VISA) when declaring/using I/O devices. Backward compatibility is maintained, even though users are "encouraged" to use new-style devices.

The User's old program I/O operates exactly as before VEE 8.0. The legacy SICL-style devices can run but can no longer be found unless you go to File => Default Preferences, and check the Enable Pro 8.0 Legacy I/O under the I/O tab.

Note: If you are using a GPIB to LAN interface, due to lengthy time-out periods when trying to find LAN devices from the root node, Agilent recommends launching the find operation from the GPIB interface. Find operations launched in this manner will work properly and quickly.

L oad Sample: This button launches a new Agilent VEE and opens a VEE sample program. VEE will automatically select a proper sample program according to the instrument highlighted.

Add Instruments: This button allows you to add an instrument to the list. It will open the Add Interface/Device dialog box, then the Instrument Properties dialog box. You can configure the instrument by filling out the fields in those dialog boxes.

Instrument Properties...: This command allows you to edit the selected interface configuration. Clicking on Properties opens the Interface Properties dialog box. You can also double click on the interface that you want to edit to open the properties dialog box.

Save I/O Configuration: Click on this button to save the instrument configuration in the vee.io configuration file.This button is grayed out if the instrument configuration is embedded in the VEE program.

Print I/O Configuration: This button brings up the Print dialog box.

Restore to Saved I/O Configuration: This button discards all the operations you have made in the Instrument Manager and loads the instrument configuration from the saved vee.io configuration file.

Help: This button opens the Instrument Manager help topic.

Create I/O Objects: These buttons allow users to create an I/O object for the selected instrument. With an instrument is highlighted, the Create Direct I/O Object is always active. This means you can select and place a Direct I/O Object for the instrument. With other instrument configurations, the Plug&play Driver, NI-DAQ Driver, IVI-COM Driver, Panel Driver, and Component Driver buttons may be active at this point, depending on which drivers you have installed.

Instrument Pane

Instrument pane displays a list of instruments and interfaces in a tree view. The tree view contains three types of nodes: My Configuration (the root), interfaces, and instruments. Click on a node to select it. The selected node controls the actions performed by toolbar buttons. Double clicking an instrument in the list creates a Direct I/O object in the workspace for the instrument selected.

Context Menu

Right-clicking a node in the instrument list displays a context menu. The content of the context menu depends on which type of node is selected.

For the root node, context menu includes three commands:

    • Find Instruments

    • Auto Discovery Settings: This command brings up the Auto Discovery Settings dialog, which controls some of the actions performed during instrument discovery.

    • If Detect only is selected, the Find Instruments button simply detects whether a device is present at each bus address.

    • If Detect, identify, and configure... is selected, the Find Instruments button also performs an identification and driver configuration for each instrument detected. (This is the same configuration performed by the Configure Drivers command in instrument context menus.)

    • If Ask before sending... is checked, a confirmation dialog is presented before *IDN? is sent to identify each instrument. If not checked, *IDN? is sent to all instruments without operator confirmation. You may want the confirmation dialog if your system contains old, non-IEEE-488.2 instruments.

    • Add Instruments...

For Interface nodes, context menu contains three commands:

    • Find Instruments

    • Properties...: This command brings up the interface configuration dialog box for VXI, and GPIB legacy interfaces.

    • Add Instruments...

For Instrument nodes, context menu includes multiple commands in three groups:

    • Create IO Object group: Click on one of the commands to add an instrument I/O object to the work area. Commands that are not available for the selected instrument will not appear.

You can also drag an instrument from the list to Main workspace to add an instrument I/O object. Agilent VEE will add an instrument I/O object if there is only one instrument I/O object can be added, or an instrument I/O object list appears allowing you to choose one I/O object to add.

This group will disappear when program is in panel view to avoid users to add IO objects into panel view.

    • Configuration group: there are two commands in this group.

      • Add Instrument...

      • Configure Drivers: This command performs an identification of the selected instrument and configures any available drivers for that instrument. Note that only IEEE-488.2 (and most VXI) instruments can be identified. Instruments on less sophisticated interfaces, like RS-232, cannot be automatically detected or identified.

      • Configure Drivers operates on a selected instrument in the Instrument List. It is only available when an instrument is selected; if the root node or an interface is selected, this button is grayed out (unavailable).

      • If this button is grayed out when an instrument is selected, then no instrument I/O is available on your system. In this case, you need to install the appropriate I/O Libraries (VISA, SICL, etc.) to support your instrument interface(s).

      • Load Sample

      • Property group: there are two commands in this group:

        • Delete Instruments: This command deletes the currently selected instrument from the instrument list. Interface nodes are automatically removed when all instruments associated with the interface are removed. If you make a mistake, just click the Restore to Saved I/O Configuration toolbar button to recover.

        • Instrument Properties...: This command allows you to edit the selected instrument configuration. Clicking on Properties opens the Instrument Properties dialog box.

More about Auto Discovery

Find Instruments operates on the selected node in the Instrument List. If the root node (typically "My Configuration") is selected, then all local interfaces are searched. If an individual interface is selected, only that interface is searched. GPIO and RS-232 interfaces cannot be searched for instruments because they do not support any standard protocol for automatic instrument detection.

The Find Instruments operation does not search LAN-gatewayed interfaces when run from the root node, but it will search for remote instruments if run from a gatewayed interface node. The Find Instruments operation does not search for new LAN-gatewayed interfaces. The initial entry for a gatewayed interface must be made manually.

The search can produce the following results in the Instrument List area:

Instruments that were already listed in the instrument configuration and are physically present on the interface are marked by a computer icon.

Instruments that were not already listed in the instrument configuration file, but are physically present on the interface are added to the list and marked by a question mark.

Instruments that were already listed in the instrument configuration, but are not physically present on the interface are not marked.

Note that the Auto Discovery process does not delete instruments from the current configuration. It can add new entries and note if the existing entries correspond to live instruments or not. However, an entry is not removed simply because the corresponding instrument is not alive when the Find Instruments button is pressed. This conservative approach is welcomed by most users in most situations. The one small disadvantage is that you cannot create an I/O configuration that is exactly equal to the currently-connected instruments by pressing just one button. If you need to create a configuration which contains only the instruments connected locally at a given time, first delete all the instrument entries, then press Find Instruments.

More about Saving an I/O Configuration

The instrument configuration can be saved in a separate file or embedded in the VEE program. If you want to use a separate file, the configuration is saved in vee.io. A VEE program that has I/O objects relies on the instrument I/O configuration file to find the instruments referenced in the program. If the program is not matched to the configuration file (for example, if a program file is copied from one machine to another without copying the corresponding vee.io file), an object might not be able to execute because its associated instrument is not configured.

As an alternative, instrument configuration information may be embedded in the VEE program file. To create an embedded configuration, choose File [image] Save As… (or Save for a new program file), and check the Save I/O configuration with program box in the Options area. Then click OK to save the program. When the I/O configuration is saved with the program, the Save button in the Instrument Manager is disabled.

The Instrument Manager displays whether the I/O configuration is from a separate vee.io file or is embedded in the program.

Notes

An I/O object (except Plug&play and IVI-COM Driver objects) may be operated with or without actual instruments connected to the computer. If you want to control a live instrument, you must set a correct, non-zero address and enable Live Mode. The address and Live Mode setting are controlled by way of the Instrument Properties tool window. If the address is zero or if Live Mode is off, the instrument object operates but does not attempt to communicate with a physical instrument. Plug&play and IVI-COM Driver objects ignore the Live Mode setting when it is off, and always try to access the physical instrument.

Before VEE can communicate with your physical instruments, the instruments (and their interfaces) must be properly configured. Refer to your I/O Libraries installation instructions for more information.

For instrument-specific help, select Help from the object menu of a Panel Driver or Component Driver object.

Panel Drivers can be used interactively or within a program. To set the value of an individual component, click on the field containing the value of the component and complete the resulting dialog box. To make a measurement and display the result, click on the corresponding numeric readout or XY display inside the Panel Driver open view.

It is possible to have more than one object controlling a single instrument. It is also possible to have multiple copies of the same driver, each controlling a different physical instrument. In either case, it is the configured name that determines which object controls which instrument.

Location

I/O [image] Instrument Manager

See Also

Advanced Instrument Properties, Advanced I/O, Agilent IO Monitor, Component Driver, Direct I/O, Instrument Properties, Panel Driver, To/From VXIplug&play, To/From IVI-COM, and To/From IVI-COM - Advanced.

To Delete an Instrument Configuration, To Add an Instrument Configuration , To Edit an Instrument Configuration

I/O Configuration Techniques, I/O Control Techniques, Logical Units and I/O Addressing


Instrument Properties

A dialog box that allows you to configure instruments.

Use

Use the Instrument Properties dialog box to add a new instrument configuration or to edit an existing configuration. You can use Instrument Properties to configure GPIB, Serial, GPIO, VXI, TCPIP, NIDAQ, and USB instruments and their associated objects, such as Direct I/O, Plug&play Drivers, IVI-COM, and Panel Drivers.

Dialog Information

The Instrument Properties dialog box provides the following fields and buttons:

Note
Use the Tab key to tab from field to field, or click on the desired field with the mouse. Do not press Enter (or Return) until you are finished with the dialog box. Pressing Enter (or Return) will cause the dialog box to close -- it is equivalent to pressing OK.

Name - Enter a unique name to identify this particular instrument configuration. Note that more than one configuration, each identified by a unique name, can control a single instrument, but this technique is not recommended. You cannot use the same name for two different instruments.

Interface - Specifies the type of hardware interface used to communicate with the instrument (the default is GPIB). Click on GPIB to display a list of available interface types. By default, VEE only supports seven types of interface. They are GPIB, ASRL,TCPIP,USB, NIDAQ, VXI and GPIO. If you want to use legacy SICL style interfaces for GPIB and Serial , go to File => Default Preferences, under the I/O tab, select the Enable Pro 8.0 Legacy I/O.

Board Number - Each board of this interface type is numbered beginning with 0. The default is 0.

VISA Alias - The alias for the VISA address string. It provides a simpler method for identifying the instrument. For example, you may use USBDevice1 as the alias address for a USB device, which VISA address is USB9::2391::1031:US432109::0::INSTR. This VISA Alias must be the same as it is configured in Agilent IO library.

VISA Address - The VISA address of the instrument. Depends on the interface, there are difference formats of VISA address. The following table shows the VISA address format and example for each type of interface.

Interface | VISA Address | Example
GPIB | GPIB[board]::GPIB address::INSTR | GPIB0::20::INSTR -- 0 is the board number, 20 is the GPIB address of the instrument.
ASRL | ASRL[board]::INSTR | ASRL1::INSTR -- 1 is the board.
USB | USB[board]::USB address::INSTR | USB9::2391::1031:US432109::0::INSTR -- 9 is the board number, 2391::1031:US432109::0 is the USB address of the instrument.
TCP/IP | TCPIP[board]::host address[::LAN device name]::INSTR | TCPIP0::jetscrm3::inst0::INSTR -- 0 is the board number, jetscrm3 is the host address (this could also be an IP address such as 129.82.135.12).inst0 is the default LAN device name.

Drive Type - The Driver Type of NI instruments. You could select one from the drop-down list. VEE supports six types of NI driver. They are NI-DAQmx, NI-DAQ, NI-DMM, NI-FGEN, NI-SCOPE, and NI-SWITCH.

Address (eg 714) - The I/O address of your legacy instrument. The default is 0. (When you enter a non-zero address, Live Mode changes to ON.) For more information about setting addresses, refer to Help => Contents and Index => Tell Me About... => Configuring Instruments.

Gateway - Specifies the LAN gateway's host name when a VEE process is accessing instruments connected to a remote computer. The default value is This host. For more information about advanced I/O control, refer to Help => Contents and Index => Tell Me About... => Advanced I/O Topics.

Advanced... - Clicking on the Advanced... button will open the Advanced Instrument Properties dialog box. From the Advanced Instrument Properties dialog box, you can configure the device driver, and the communications parameters for each of the interface types listed above. Refer to the separate Help topic for Advanced Instrument Properties.

OK - Once you have completed your configuration, click OK to confirm your changes.

Location

I/O [image] Instrument Manager… then select an instrument by double-clicking its line in the Instrument List.

See Also

Advanced Instrument Properties, Advanced I/O, Agilent IO Monitor, Component Driver, Direct I/O, Instrument Manager, Panel Driver, and To Add an Instrument Configuration.


Int16

An object that outputs a constant 2-byte integer scalar or 1D array.

Use

Use Int16 to set an integer constant or to get user input. Click on the entry field to enter a value.

Example

To use Int16 as a prompt on a panel view, change the name of the Int16 object to a prompt such as Enter the number of seconds to delay:. The user fills in the requested information in the entry field.

Type in the formula 12*1024 into the Int16 and it will calculate the result.

Properties

General tab:

DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are scalar and Array 1D.

 ArraySize: - When DataShape 1D Array is selected, ArraySize sets the length of the array.

 ArraySizeFixed - When this property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D Array is selected.

 ShowArrayIndices - When this property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is True.

Wait for Input - When this property is True, the object does not operate until the object's value is changed. When the check box is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When this property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

Initialization group:

 InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When this property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When this property is True, the InitialValue is set at Activate time. Default is False.

NumberFormat:

Global Format - Use the default format. Default is on.

Integer: - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin available on most data constants.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires an integer value, either a Scalar or an Array 1D. The Constant is re-configured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Int16 is configured to be an array.

Location

Data [image] Constant [image] Int16

See Also

Alloc Int16, Complex, Constant, Coord, Date/Time, Selection Control, Default Preferences, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real32, Real64, Text, Boolean, and Toggle Control.

To Use a Data Constant


Int32

An object that outputs a constant 4-byte integer scalar or ID Array.

Use

Use Int32 to set an integer constant or to get user input. Click on the entry field to enter a value.

Example

To use Int32 as a prompt on a panel view, change the name of the Int32 object to a prompt such as Enter the number of seconds to delay:. The user fills in the requested information in the entry field.

Type in the formula 12*1024 into the Int32 and it will calculate the result.

Properties

 DataShape: - Sets the initial data shape of the value(s) to be output with this object. Possible values are scalar and Array 1D.

 ArraySize: - When DataShape 1D Array is selected, ArraySize sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D A rray is selected.

 Stepping Category: - (Disabled when DataShape is Array 1D.

 ShowArrayIndices - When this property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is True.

  • EnableStepping - When this property is True, stepping controls appear at the right end of the entry field to let you scroll through values. Default is False.

  • DetentSize - When the EnableStepping property is True, this sets the size between values when using the stepping controls to scroll through values. Default is 1.

 Wait for Input - When this property is True, the object does not operate until the object's value is changed. When the property is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When this property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

 InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When this property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When this property is True, the Initial Value is set at Activate time. Default is False.

NumberFormat:

 Global Format - Use the default format. Default is on.

 Integer: - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin available on most data constants.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires an integer value, either a Scalar or an Array 1D. The Constant is re-configured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Int32 is configured to be an array.

Location

Data [image] Constant [image] Int32

See Also

Alloc Int32, Complex, Constant, Coord, Date/Time, Selection Control, Default Preferences, UInt8, UInt16, Int16, Int64, PComplex, Real32, Real64, Text, Boolean, and Toggle Control.

To Use a Data Constant


Int32 Input

An object that displays a pop-up dialog box that accepts integer number input.

Use

Use Int32 Input to prompt the user to enter an integer number, accept the number, and check the number with a user-defined test for validity.

In the pop-up dialog box, when the OK button is pressed, the integer number input by the user is output on the Value output pin. When the Cancel button is pressed, a 1 is output on the Cancel output pin.

Open View

  • Prompt/Label - The string that prompts the user to fill in the text field. You may add this parameter as a data input. Default is Enter Integer Value:

  • Default Value - The text that is in the dialog's input field before anything is typed. If the user presses OK without typing anything, this text is output. You may add this parameter as a data input. Default is 5

  • Value Constraint - The equation that tests the input text for validity. You can use any mathematical expression or call a UserFunction. You may add this parameter as a data input. Default is 0<=value AND value<=10; which means it checks for user input of a value between 0 and 10. To accept any value, use the expression 1.

  • Error Message - The text that is output in a message box if the user input does not meet the Value Constraint. You may add this parameter as a data input. Default is You must enter a integer between 0 and 10.

Properties

  • PopupTimeoutEnabled - When this property is True, a Timeout output pin is added to the object. Default is False.

  • PopUpDuration - Sets the length of time the pop-up dialog box is displayed. After this period of time, the dialog box times out and a value of 1 is output on the Timeout output pin. No other outputs pins have data if the Timeout pin executes. This field is only available when the Timeout Enabled check box is selected. Default is 60 seconds.

  • PopupOKLabel - Sets the button label to OK if True. You may also use alternative wording if your users are not native English speakers. Regardless of the wording, the button's function remains the same.

  • PopupCancelLabel - Sets the button label to Cancel if True. You may also use alternative wording if your users are not native English speakers. Regardless of the wording, the button's function remains the same.

  • PopupPasswordMasking - When this property is True, the input text is echoed as asterisks (*). This feature is useful when the operator is entering sensitive data such as a password. The string that is output on the Value output pin is not masked. Default is False.

Notes

The default location of the pop-up dialog box is approximately at the center of the work area. If you move it, next time it will pop-up to the new location.

The title text of the error message dialog box is the same as the Int32 Input object title.

To respond to the pop-up dialog box using only the keyboard: when the dialog box pops up, start typing and use the Enter and Esc keys. Use the Tab key to move between the input field and the buttons and then select the buttons with the Space bar.

The pop-up dialog box and the error dialog box are only displayed while the program is running. While the pop-up dialog box is displayed, the entire program pauses execution, then continues when the dialog box is closed.

Location

Data [image] Dialog Box [image] Int32 Input

See Also

File Name Selection, List Box, Message Box, Real64 Input, Text Input, UserObject, and Object Menu

To Use a Data Input Dialog Box


Int64

An object that outputs a constant 8-byte integer scalar or 1 D Array.

Use

Use Int64 to set an integer constant or to get user input. Click on the entry field to enter a value.

Example

To use Int64 as a prompt on a panel view, change the name of the Int64 object to a prompt such as Enter the number of seconds to delay:. The user fills in the requested information in the entry field.

Type in the formula 1024*1024 into the Int64 and it will calculate the result.

Properties

 DataShape: - Sets the initial data shape of the value(s) to be output with this object. Possible values are scalar and Array 1D.

 ArraySize: - When DataShape 1D Array is selected, ArraySize sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D A rray is selected.

 Stepping Category: - Disabled when DataShape is Array 1D.

 ShowArrayIndices - When this property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is True.

  • EnableStepping - When this property is True, stepping controls appear at the right end of the entry field to let you scroll through values. Default is False.

  • DetentSize - When the EnableStepping property is True, this sets the size between values when using the stepping controls to scroll through values. Default is 1.

 Wait for Input - When this property is True, the object does not operate until the object's value is changed. When the property is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When this property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

 InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When this property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When this property is True, the Initial Value is set at Activate time. Default is False.

NumberFormat:

 Global Format - Use the default format. Default is on.

 Integer: - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin available on most data constants.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires an integer value, either a Scalar or an Array 1D. The Constant is re-configured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Int64 is configured to be an array.

More About Int64 and Execution Mode

Int64 has the longest precision for representing an integer. Agilent VEE provides two built-in numeric constants to represent the maximum and minimum values of int64: MaxInt64 and MinInt64. Constants in different Execution Modes will be explained as different types, see the following table for some examples.

constants | ExecMode VEE 8 | ExecMode VEE 7 | ExecMode VEE 6 | ExecMode VEE 4&5
1 | Int32 | Int32 | Int32 | Real
1G | Real64 | Real64 | Real | Real
2147483648 (maximum value of Int32 + 1) | Int64 | Real64 | Real | Real
2147483647 (maximum value of Int32) | Int32 | Real64 | Real | Real
9223372036854775808 (maximum value of Int64 + 1) | Real64 | Real64 | Real | Real
9223372036854775807 (maximum value of Int64) | Int64 | Real64 | Real | Real
-9223372036854775808 | Real64* | Real64 | Real | Real
MinInt64** | Int64 | Int64 | Int64 | Int64

* If you want Agilent VEE to treat -9223372036854775808 as Int64, use the built-in constant MinInt64 instead.

** MinInt64 and MaxInt64 are two built-in numeric constants. They always behave like an Int64 constant. The user can also use the MinInt64 and MaxInt64 built-in constants under different Execution modes.

Location

Data [image] Constant [image] Int64

See Also

Alloc Int64, Complex, Constant, Coord, Date/Time, Selection Control, Default Preferences, UInt8, UInt16, Int16, Int32, PComplex, Real32, Real64, Text, Boolean, and Toggle Control.

To Use a Data Constant


Int32 Knob

An object that outputs the integer value of the knob.

Use

Use Int32 Knob to input Int32 values. Int32 Knob is particularly useful on a panel view.

Open View Parameters

The open view displays fields for the knob's current value, minimum, and maximum values, and the knob control.

Properties

Orientation - Sets how the Knob is displayed. Default is Horizontal.

 ShowDigitalDisplay - If the property is True, the current value of the knob is displayed in an edit field at the bottom of the open view of the object. When you modify this value, the position of the knob changes. Default is True.

ShowTic - Controls visibility of scale’s tic marks and labels. Default is True.

 LabelSpacing: - Controls which tic marks are labeled with the scale values. Default is EveryOtherTic.

 DetentSize: - Sets the distance between the values that are available from the Knob. If other values are entered, they are rounded to the nearest detent. Any real Detents are truncated to Int32. Default is 1.

Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When the property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When the property is True, the InitialValue is set at Activate time. Default is False.

Number Format - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Notes

Initialization is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, Disable Editing, MaxValue, MinValue, and Detents:

The Default Value input allows you to programmatically change the current value. This input requires an Int32 Scalar value.

The Reset input allows you to programmatically set the value to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the current, minimum, and maximum values can be changed in the open view.

The MaxValue and MinValue inputs allow you to programmatically set the min and max value fields. These inputs require a real scalar value, which is then converted to an Int32.

The Detents input allows you to programmatically set the detent value.

Location

Data [image] Continuous [image] Int32 Knob

See Also

Complex, Selection Control, Int32, Int32 Slider, PComplex, Real64, Real64 Knob, Text, Toggle Control, and Object Menu

To Use a Data Slider and Knob


Int32 Slider

An object that outputs the integer value of the slider.

Use

Use Int32 Slider to input Int32 values. Int32 Slider is particularly useful on a panel view.

Open View Parameters

The open view displays fields for slider value, min, max, and slider control.

Properties

Orientation - Sets how the Slider is displayed. Default is Vertical.

 ShowDigitalDisplay - If the property is True, the current value of the slider is displayed in an edit field at the top of the open view of the object. When you modify this value, the position of the slider control changes. Default is True.

ShowTics - If the property is True, the slider shows marks and labels for values between the min and the max. The default is True. For programs prior to VEE revision 4.0, the default is False.

 LabelSpacing: - Controls which tic marks are labeled with the scale values. Default is Every Other Tic.

 Detent Size: - Sets the distance between the values that are available from the Slider. If other values are entered, they are rounded to the nearest detent. Any real Detents are truncated to Int32. Default is 1.

Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When the property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When the property is True, the InitialValue is set at Activate time. Default is False.

NumberFormat - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, Disable Editing, MaxValue, MinValue, and Detents:

The Default Value input allows you to programmatically change the current value. This input requires an Int32 Scalar value.

The Reset input allows you to programmatically set the value to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the current, minimum, and maximum values can be changed in the open view.

The MaxValue and MinValue inputs allow you to programmatically set the min and max value fields. These inputs require a real scalar value, which is then converted to an Int32.

The Detents input allows you to programmatically set the detent value.

Location

Data [image] Continuous [image] Int32 Slider

See Also

Complex, Selection Control, Int32, Int32 Knob, PComplex, Real64, Real64 Knob, Real64 Slider, Text, Toggle Control, and Object Menu

To Use a Data Slider and Knob


Interface Event

An object that captures asynchronous interface events for VXI, GPIB, and serial.

Use

The Interface Event object can be configured to detect various interface events. Depending on the configuration, the object may wait for the event, giving up execution to other parallel threads, or it may simply return a boolean (0 or 1) or other indicator of the state of the interface.

If the Interface Event object has been configured to wait for the event, then upon the event the object will execute. In VEE 3 execution mode only, any thread hosted by this object will have priority over any other parallel threads, and will execute to completion. If the Interface Event object has been configured to simply return an indicator of interface state, the thread containing it will have normal priority, and will execute in parallel with any other threads.

Open View Parameters

Interface - The currently selected interface is displayed in this field. Click on this field to display a list of the currently configured interfaces. For an interface to appear in this list, at least one instrument for that interface must be configured using I/O [image] Instrument Manager.... Multiple interfaces of the same type are distinguished by their logical units (e.g.: "hpib7" and "hpib8").

Action - Determines the execution behavior of the Interface Event object upon detection of the event.

Wait - Wait for the event to occur. The object executes when the event occurs. Any thread hosted by this object will have priority over any other parallel threads, and will execute to completion when the event occurs, but is "blocked" until the event occurs. When the event occurs, a boolean TRUE (1) or an interface-event-specific bit pattern is output.

No Wait - Execute immediately, placing the current state of the configured event, as specified by a 32-bit integer, on the event output pin. This value is the boolean value FALSE (0) if the event has not occurred. If the event has occurred, a TRUE (1) or an interface-event-dependent bit pattern is returned. In the No Wait configuration, any thread hosted by the Interface Event object will have normal execution priority, and will execute in parallel with any other threads.

Event - Allows selection of specific interface events. Click on this field to display the choices. For each choice below, both the Wait and the No Wait actions are described. Note that in each case, the thread propagation priorities for Wait and No Wait are as described above.

SRQ - This is the only choice for the GPIB interface:
-- If the Action choice is Wait, the Interface Event object delays execution until a GPIB device asserts the service request line. It then places the boolean value TRUE (1) on the event output pin.
-- If the Action choice is No Wait, a boolean value FALSE (0) is output if the event has not occurred. If the event has occurred, a boolean TRUE (1) will be output on the event pin.

DAV - (Data Available) This is the only choice for the serial interface.
-- If the Action choice is Wait, the Interface Event object delays execution until data arrives in the receive buffer. The number of bytes in the receive buffer is placed on the event output pin, alerting the following object to read those bytes from the buffer.
-- If the Action choice is No Wait, the Interface Event object executes immediately giving out the number of bytes in the receive buffer from the event output pin.

Sys Reset - The Interface Event object executes when a system reset occurs on the VXI interface:
-- If the Action choice is Wait, a boolean TRUE (1) is output on the event pin when the system reset occurs.
-- If the Action choice is No Wait, a FALSE (0) is output if the system reset has not occurred.

Sys Active - When the VXI Resource Manager has finished its VXI initialization and management, it sends a Begin Normal Operation (BNO) command to the VXI interface. If Sys Active is configured, the Interface Event object executes when this occurs:
-- If the Action choice is Wait, a boolean TRUE (1) is output on the event pin when the BNO command occurs.
-- If the Action choice is No Wait, a FALSE (0) is output if the event has not occurred.

Sys Deactive - When normal VXI operation is aborted an Abort Normal Operation (ANO) or End Normal Operation (ENO) command is sent to the interface. If Sys Deactive is configured, the Interface Event object executes when this occurs:
-- If the Action choice is Wait, a boolean TRUE (1) is output on the event pin when the ANO or ENO command occurs.
-- If the Action choice is No Wait, FALSE (0) is output if the event has not occurred.

TTL Trig - When TTL Trig is configured, the Interface Event object "monitors" the VXI TTL trigger lines:
-- If the Action choice is Wait, the Interface Event object executes when a VXI device asserts one or more of the eight TTL trigger lines in the VXI backplane, placing a 32-bit integer on the event output pin. Only the low byte of this integer is significant. It is a bit pattern showing which of the eight TTL trigger lines are active (bit 0 corresponds to trigger line 0, bit 7, to trigger line 7). Each bit set (1) indicates that the corresponding line has been triggered. For example, 00010001 indicates that TTL lines 0 and 4 have been triggered.
-- If the Action choice is No Wait, the boolean FALSE (0) is output if no triggers have occurred.

ECL Trig - When ECL Trig is configured, the Interface Event object "monitors" the VXI ECL trigger lines:
-- If the Action choice is Wait, the Interface Event object executes when a VXI device asserts one or more of the four ECL trigger lines in the VXI backplane, placing a 32-bit integer on the event output pin. The low byte of this integer is a bit pattern showing which of the four ECL trigger lines are active. (Bit 0 corresponds to trigger line 0, bit 3, to trigger line 3.) Each bit set (1) indicates that the corresponding line has been triggered. For example, 00001001 indicates that ECL lines 0 and 3 have been triggered.
-- If the Action choice is No Wait, the boolean FALSE (0) is output if no triggers have occurred. Note that some VXI card cages may choose to implement only two ECL trigger lines.

EXT Trig - When EXT Trig is configured, the Interface Event object "monitors" the VXI EXT trigger lines:
-- If the Action choice is Wait, the Interface Event object executes when an external device asserts an embedded controller's "Trig In" input. Up to four external trigger inputs can occur. A 32-bit integer is output on the event pin when the Interface Event object executes. The low byte of this integer is a bit pattern showing which of the four EXT trigger lines are active. (Bit 0 corresponds to external trigger 0, bit 3, to external trigger 3.) Each bit set (1) indicates that the corresponding trigger has occurred. For example, 00001001 indicates that EXT trigger lines 0 and 3 have been triggered.
-- If the Action choice is No Wait, the boolean FALSE (0) is output if no triggers have occurred. Some controller implementations may have no external trigger inputs.

Unknown Interrupt - If Unknown Interrupt is configured, the Interface Event object checks for any VME interrupts from a VME or VXI device not in the VXI controller's servant area:
-- If the Action choice is Wait, such an interrupt causes the Interface Event object to execute. The 32-bit value returned is the value placed on the VXI Bus when the device does an interrupt acknowledge (IACK).
-- If the Action choice is No Wait, the boolean FALSE (0) is output if no interrupt has occurred.

Unknown Signal - If Unknown Signal is configured, the Interface Event object checks for any signal register write from a VXI device not in the VXI controller's servant area:
-- If the Action choice is Wait, such a signal causes the Interface Event object to execute. The 32-bit value returned is the contents of the signal write register.
-- If the Action choice is No Wait, the boolean FALSE (0) is output if no signal has occurred.

Notes

The execution behavior of the Interface Event object can either be asynchronous or synchronous, as determined by the choice of the Action parameter. NO WAIT specifies a synchronous, polling behavior. The object executes immediately, and any attached thread will have the same priority as all other threads currently executing. Choosing WAIT causes the Interface Event object to wait until the event has occurred. Any thread hosted by the object will have a higher priority, and will execute to completion, blocking all other concurrently executing threads.

Timeout Control Pin - Sets timeout period the object waits trying to acquire a locked interface to service an event. An error occurs if no interface is acquired.

Location

I/O [image] Advanced I/O [image] Interface Event

See Also

Instrument Event, and Interface Operations.

To Poll GPIB Instruments


Interface Operations

An object that uses transactions to send low-level interface commands and data by way of GPIB, VXI, and serial.

Interface Operations should be used for interface-specific tasks, or for special cases where communication with devices via Direct I/O or an Instrument Driver does not afford the necessary level of control.

Use

Use Interface Operations for low-level operations such as:

Sending non-standard GPIB addressing sequences.

Sending a GPIB group trigger message, or pulling on VXI trigger lines.

Sending arbitrary bytes via GPIB, with or without ATN true.

Sending clear and reset commands to either the VXI or GPIB interfaces.

Sending IEEE 488.1 defined multi-line messages.

Sending interface lock and unlock messages to the serial interface.

To use Interface Operations you must add one or more transactions. To do this, click on Add Trans in the object menu. Transactions are listed as lines of text in the open view of the object. To edit a transaction, double click on the transaction and complete the resulting dialog box.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Properties

Interface: - Displays the bus configuration and allows you to change to another interface. Multiple interfaces of the same type are distinguished by their logical units (e.g., "hpib7" and "hpib8").

 Timeout: - Sets the timeout period. Can be set with a control input pin.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

I/O [image] Advanced I/O [image] Interface Operations

See Also

Advanced I/O, Agilent IO Monitor, Formula, Instrument Manager, and To Edit a Transaction


Interface Properties

A dialog box used to configure various interface addresses.

Use

You can use the Interface Properties dialog box to configure or edit a VXI, or GPIB(Legacy)interface address.

Open View Parameters

The following parameters are configured from the Interface Properties dialog box:

Interface: - This is the interface type to be configured (the default interface type is the type you selected from the Instrument List.

Address: - This is the logical unit number of the interface you wish to configure or edit.

Gateway: - Specifies the LAN gateway's host name when a VEE process must access the instruments connected to a remote computer. The default value is This host.

Location

I/O [image] Instrument Manager...

From the Instrument List on the Instrument Manager dialog box, select (highlight) one of the interface icons such as, VXI or GPIB(Legacy), then click on the Properties button. This will bring up the Interface Properties dialog box.

See Also

Advanced I/O, Advanced Instrument Properties, Instrument Properties, To Add an Instrument Configuration, and To Edit an Instrument Configuration.


IP Address

Retrieves the IP address of the host machine.

Location

System [image] Environment [image] IP Address


Is Leap Year?

Returns a boolean value of true if it is a leap year.

Location

System [image] DateTime [image] Is Leap Year?


Is Path Rooted?

Retrieves a boolean value based on whether the path provided is rooted or not. For example, vee\src is not rooted while \vee\src is.

Location

System [image] Path [image] Is Path Rooted?


JCT

An object that outputs the value from the most recent data input (one of multiple inputs) that is activated.

Use

Use JCT like a wired OR to connect the data output pins of two or more objects to one data input pin of another object. JCT is often used in feedback loops for data initialization. JCT passively transmits data. In VEE 4.0 and later, a JCT is required in threads using feedback.

Notes

JCT is useful for setting up initial conditions.

Inputs to JCT are asynchronous data inputs. This means that JCT operates any time any of its data inputs is activated. When more than one pin on the JCT is activated before the JCT can operate, the incoming data is queued up in the order in which it was received. The JCT then activates its output repeatedly much like an iterator until the data queue is empty. If the input data pin is activated by a feedback loop, multiple activations are ignored.

One of the common uses of JCT is in a feedback loop where an initial value is first supplied through one of the inputs, and feedback values are then supplied through one or more of the other data inputs.

Location

Flow [image] Junction

See Also

DeMultiplexer, Properties (Object), and Object Menu


Join

Join an array of text values with a text separator. For example, the values one; two; three; and four. Use a comma for a separator and you would have one, two, three, four. This is a quick way to create a CSV file.

Location

System [image] String   [image] Join


Junction

See JCT.


Label

An object that is used to put a text label on the Panel View.

Use

Use Label to create labels or headings on the Panel View. This object does not need to execute, and its background color blends into the background color of the Panel View.

Open View

The current Label string is shown. Default is Label. To change the Label, change the object's title using Properties in the object menu, or use a data input.

Properties

Justification - Specifies the layout of the text within the object border. Default is Left.

Notes

The default object color for the Label is the same as the default Panel View color so that the Label background blends into the Panel View.

The default Border setting for the Label object on the Panel View is None.

If using the data input for the label value, note that the Label object will not auto-size at run time to fit the string’s length. Label clips the text of a string sent to it on the data input if the string is longer than the Label object. Be sure to size the Label object large enough so the string fits when using the data input.

Location

Display [image] Label

See Also

Beep and Text.

To Label Areas


Last Directory Access Time

Retrieves the last time the directory was accessed.

Location

System [image] Directory [image] Last Directory Access Time


Last Directory Write Time

Retrieves the last time the specified directory was modified.

Location

System [image] Directory [image] Last Directory Write Time


Last Error

A View menu item that allows you to retrieve the last Error dialog box that was generated in your VEE program.

Use

Last Error allows you to retrieve the last Error dialog box that was generated in your VEE program. You can click the Go To button on the Error dialog box and the detail view of the VEE program will be brought into the VEE workspace. As long as the program remains in an Error state, the UserObject or UserFunction where the error occurred will be highlighted. If the program is no longer in an Error state, for example if the program has been stopped, the object will not be highlighted.

Dialog Information

The Last Error dialog box contains the following information and buttons:

Error message and error number - The main window of the Last Error dialog box will contain a brief explanation of the error that was generated, and will identify the Object Title and the Object Type where the error occurred. The Error number will also be identified.

Go To - Clicking on the Go To button will bring up the detail view of the VEE program, and if the program is still in an Error state, the UserObject or UserFunction where the error occurred will be highlighted.

Call Stack - Clicking on the Call-Stack button will bring up the Call Stack dialog box. The Call Stack may contain more information regarding where in your program the Error occurred.

Close - Closes the Error dialog box.

Help - Clicking on Help will open the Help topic that provides more information on the Error number you received.

Notes

Errors that are trapped and handled by an Error pin will not be retrievable using Last Error.

Location

View [image] Last Error

See Also

Error Output (Object Menu), Call Stack, errorInfo(), and Raise Error.


Line Probe

Displays the container information that is transmitted on a line between two objects.

Use

Use Line Probe as a debugging tool to examine the container transmitted on a line. When you use Line Probe, the cursor changes to a magnifying glass, and remains in that mode until you click in the work area. Click on the line you want to examine. This opens a dialog box displaying the current container on the line.

If the container on the line is not nil, the dialog box displays the current type, shape, and size of the containers. Data values of up to Array 2D are shown. If any of the dimensions of the container are mapped, the mapping values are shown for each dimension.

Control inputs often have no data on them. Sequence output pins never have data on them. If an object has not yet operated, the lines connected to its inputs and outputs may show nil or old data.

Notes

To view the endpoints of a line, select Line Probe and drag the pointer to the line. Click the left mouse button over the highlighted line to display the line’s current attributes.

To view the endpoints of a line without showing its data, select Line Probe and hold down the mouse button when the pointer is over the line. Move the pointer away from the line before releasing the button.

You can also check the current data from inside the terminals of an open view object by double-clicking on the terminals.

Short Cuts

To view simple scalar values and the endpoints of a line, simply place the mouse pointer over the line. Pausing over the line displays the value of the container (if it is simple enough to display) and highlights the endpoints. Click on the line with the left mouse button to display complete container information.

If a line between two pins is short and only the terminal names appear while paused over the line, press Shift to force the mouse pointer to Line Probe.

Location

Debug [image] Line Probe

See Also

Default Preferences, and Properties (Object).

To View the Data on a Line


List Box

An object that displays a pop-up dialog box that displays a list to the user.

Use

Use List Box to display a list message to the user. The user responds by selecting one (or more) of the choices on the dialog box. You may customize the text on the buttons.

In the pop-up dialog box, when a selection is made, the selection is output on the Text output pin and its index into the list is output on the Index output pin. When multiple selections are made, an array of text is output on the Text output pin and an array of indices is output on the Indices output pin.

Open View

  • List Entries Edit ... - Allows you to edit the list of choices displayed on the List Box pop-up dialog box. You may add this parameter as a data input.

  • Default Entry - Allows you to select the default entry from the choices in List Entries to appear on the pop-up dialog box. You may add this parameter as a data input.

  • Allow Multiple Selections - When the check box is selected, the user may choose one or more selections from the list. Also two additional buttons are added to the pop-up dialog box: Select All and Clear All.

Properties

  • PopupTimeoutEnabled - When this property is True, a Timeout output pin is added to the object. Default is False.

  • PopUpDuration - Sets the length of time the pop-up dialog box is displayed. After this period of time, the dialog box times out and a value of 1 is output on the Timeout output pin. No other outputs pins have data if the Timeout pin executes. This field is only available when the Timeout Enabled check box is selected. Default is 60 seconds.

  • PopupOKLabel - Sets the button label to OK if True. You may also use alternative wording if your users are not native English speakers. Regardless of the wording, the button's function remains the same.

  • PopupCancelLabel - Sets the button label to Cancel if True. You may also use alternative wording if your users are not native English speakers. Regardless of the wording, the button's function remains the same.

  • PopupSelectAllLabel - available only when Allow Multiple Selections is selected

  • PopupClearAllLabel - available only when Allow Multiple Selections is selected

  • PopupPasswordMasking - When this property is True, the input text is echoed as asterisks (*). This feature is useful when the operator is entering sensitive data such as a password. The string that is output on the Value output pin is not masked. Default is False.

  • PopupNumDisplayedItems - Sets the maximum number of lines the List Box will display without a scroll bar. If this value is greater than the number of list entries, the dialog pop-up is sized to contain the number of list entries (no blank lines). Default is 10.

Notes

The default location of the pop-up dialog box is approximately at the center of the work area. If you move it, next time it will pop-up to the new location.

To respond to the pop-up dialog box using only the keyboard: when the dialog box pops up, use Enter and Esc keys. Or use the Tab key to move between the buttons and the selection area; select the choice(s) with the Space bar.

The pop-up dialog box is only displayed while the program is running. While the pop-up dialog box is displayed, the entire program pauses execution, then continues when the dialog box is closed.

Location

Data [image] Dialog Box [image] List Box

See Also

File Name Selection, Message Box, Int32 Input, Real64 Input, Text Input, and UserObject.

About Built-In Dialog Box Objects


List

See Selection Control.


Logging AlphaNumeric

An object that displays a Scalar or Array 1D of alphanumeric data. Logging AlphaNumeric allows data to be displayed without overwriting the display.

Use

Use Logging AlphaNumeric to display consecutive input (either Scalar or Array 1D) as a history of previous values.

Object Menu

Clear - Clears all the data that was displayed on Logging AlphaNumeric. Clear may be added as a control input.

Properties

ClearAtPreRun - When the property is True, the contents of the Logging AlphaNumeric are cleared at PreRun. Default is True.

 ClearAtActivate - When the property is True, the contents of the Logging AlphaNumeric are cleared at Activate. Default is True.

Buffer Size - Specifies the number of lines that the display buffer holds. If more than that number of lines is input to Logging AlphaNumeric the last values are kept and the previous are overwritten. Default is 256.

 NumberFormat - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

  • Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Sat 01/Jan/1994 17:01:38). Default is Standard.

Notes

A row of asterisks (***) is displayed if the current width of the Logging AlphaNumeric object is too small to display the default precision of the numeric type. Resize the object and rerun the program to display the data.

The display of ASCII values 0-31 is dependent on font and may not be readable.

Text strings longer than 2048 characters may not display properly on some platforms (operating systems). Text strings longer than 32767 characters do not display properly on any platform.

Location

Display [image] Logging AlphaNumeric

See Also

AlphaNumeric, Default Preferences, and Object Menu

To Display a Series of Values in a Log


Machine Name

Retrieves the name of the host machine.

Location

System [image] Environment [image] Machine Name


Magnitude Spectrum

An object that graphically displays a spectrum.

Use

Use Magnitude Spectrum to display Spectrums or Waveforms in the frequency domain. Waveforms are automatically converted to spectrums by way of a Fourier Transform. The X axis is in the sampling units of the input Spectrum (typically frequency).

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Mag - The name of the Y axis.

Trace1 - The name of the first trace.

Freq - The name of the X axis.

Object Menu

Auto Scale [image] - Clicking these menu items immediately rescales the display to show the entire trace. (Can be added as control pins, or set using the Scales properties tab to automatically rescale the display after data is collected.)

Auto Scale - Automatically scales both axes.

Auto Scale X - Automatically scales the X axis.

Auto Scale Y - Automatically scales the Y axis.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets the display to show the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Y-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints or plots a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When the property is True, the display is cleared at PreRun time. Default is True.

 ClearAtActivate - When the property is True, the display is cleared at Activate time. Default is True.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EditTracesAndScales to control the edit-button function of the trace legends. Default is True.

 ShowScalesLegend - In the open view, controls visibility of the scale names. Use EditTracesAndScales to control the edit-button function of the scale legends. Default is True.

 ShowScaleLabels - In the open view, controls visibility of the values labeling the scale axes. Default is True.

 ShowScrollBars - In the open view, controls visibility of the scroll bars on the X and Y scales. Default is True.

 ShowAutoScaleButton - In the open view, controls visibility of the Auto Scale Button. Default is False.

 EditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use ShowTracesLegend and ShowScalesLegend to control visibility of the trace(s) and scale(s) names.

GridType - Default is Lines.

NumMarkers - The number of markers displayed in the graph. To move markers to a different trace, go to the open view and click on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

 MarkerInterpolate - When the property is True, you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

DisplayBackColor - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view.

ScaleLabelFont - Allows you to select the font of the scale labels from the list of available fonts on your system. The default font for scale label text is set in Default Preferences on the Fonts tab for Screen Element: Graph Scale Label Text.

Traces Group: (one per trace)

Name: - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Color: - The color of the trace. Each added trace has a different color than the existing traces. Default for the first trace is yellow.

LineStyle: - The format of the line connecting data points. Default is a continuous line.

PointStyle: - The symbol that marks each data point. To show unconnected data points, select the single dot LineStyle format and the desired PointStyle symbol. Default is a dot.

Scale - If it exists for more than one Y scale, choose which scale this Trace is scaled by.

Scales property: (one per X and Y scale and extra Y scales)

Show Scale: - If you have multiple Y scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name: - The names of the scales appearing in the open view.

Automatic Scaling: - Controls whether the display automatically rescales to show the entire trace immediately after it receives data. Default is on. If this is turned off, you can rescale the display by using the Auto Scale button on the General tab, in the Layout group, or the Auto Scale command on the object menu.

Maximum: - The maximum values of the scales.

Minimum: - The minimum values of the scales.

Label Spacing: - Controls which tic marks are labeled with the scale values. Default for X scale is Every Other Tic; default for Y scale(s) is Every Major Tic.

Mapping: - The way the x and y data is mapped to the display. The mapping may be linear or log. To make a log-log plot, change both X and Y axes to Log. Default is Linear.

Log Cycles: - The maximum number of decades shown (counting down from the maximum x and y values) when Automatic Scaling is on. Log Cycles is only used when the Mapping is Log. Log Cycles is useful when a trace contains a large dynamic range in the data. Default is 4.

Scale Color - The color of any background grid or tic marks. Default is Gray.

ScaleNumberFormat: (a property appears for the X and Y scales, and for any additional Y scales.)

Global Format - Use the default format. Default is True.

Real - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

The X and Y marker values take on the same number format as the scale to which they are attached. The delta marker values for X and Y use the default number format unless you use the Time Stamp format. Then, if both markers 1 and 2 on the X scale, or both markers on the Y scale are using the Time Stamp format, the delta marker values use the Delta Time format.

Notes

Inputs must be of type Spectrum, Waveform, or Coord (Scalar or Array 1D).

Input data of type Coord is plotted by simply using its x and y values without first being converted to type Spectrum.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

When the Automatic Scaling property is on (Scales tab), the program executes faster if a complete set of data is sent to the display. Then, the display automatically rescales once. If a program sends one data point at a time to the display, the display may automatically rescale after each data point, which will slow down program execution. In this case, use a Collector object to create an array, then send the array to the display.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A Text field named Scale with a value X, Y (or Y1), Y2, or Y3. The Scale field is required. An error occurs if it is omitted.

One or more of the following fields:

Name - Changes the scale name in the open view. Must be a text value.

Min - Sets the X scale minimum. Must be an integer or real value.

Max - Sets the X scale maximum. Must be an integer or real value.

Mapping - Must have a text value of Linear or Log.

AutoScale - Controls automatic scaling. Must have a text value of On or Off.

You can add Print and Plot control input pins. On Windows, these inputs behave the same way, using the settings in Windows’ Print Setup dialog box (File [image] Print Setup…). If the current Printer Setup is in Print to File mode, you may specify the destination file or directory name as string data on the Plot control input. If no control input value is given, the file or directory name specified in Printer Setup will be used.

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties window. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers group. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display’s Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the display's Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] Spectrum (Freq) [image] Magnitude Spectrum

See Also

Magnitude vs Phase, Phase Spectrum, Polar Plot, Default Preferences, Spectrum (Freq), and Waveform (Time).

To Display a Waveform, To Set Markers in the Display, To Get and Set Marker Properties, and Object Menu


Magnitude vs Phase

An object that displays a polar plot of Magnitude against Phase of a complex Spectrum.

Use

Use Magnitude vs Phase to display Spectrums or Waveforms. Waveforms are automatically converted to spectrums by way of a Fourier Transform. The Radius of each data point is the spectrum's magnitude; the Angle is the Spectrum's phase in the current trig units.

You can change the display between Polar and Smith Chart modes by using Properties on the object menu. You change from Lines to Smith Chart.

Marker values are displayed in polar format (r:radius, a:angle) for the Polar grid type and complex impedance or admittance format for Smith Chart and Inv Smith Chart grid type.

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Mag - The name of the radius scale.

Span: - The vertical dimension of the display. When the origin is centered on the display, the Span is twice the radius. This parameter controls the scaling of the display. Default is 2.

Trace1 - The name of the first trace.

Polar Reference Location - Specifies the part of the polar plot displayed. This is quicker than scrolling to the area. Changing the reference point in the entry field scrolls the part of the graph specified (such as Center) to the location specified (such as (0, @0)).

Ref Radius: - The radius value of the bold graticule circle.

Object Menu

Auto Scale [image] Auto Scale - Immediately rescales the display to show the entire trace. Auto Scale resets the polar reference location to Center (0,@0). (Can be added as a control pin, or set using the Scales properties tab to automatically rescale the display after data is collected.)

Auto Scale X - Not available.

Auto Scale Y - Not available.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets the display to show the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Radius-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints or plots a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When the property is True, the display is cleared at PreRun time. Default is True.

 ClearAtActivate - When the property is True, the display is cleared at Activate time. Default is True.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EditTracesAndScales to control the edit-button function of the trace legends. Default is True.

 ShowScalesLegend - In the open view, controls visibility of the scale names. Use EditTracesAndScales to control the edit-button function of the scale legends. Default is True.

 ShowScrollBars - In the open view, controls visibility of the scroll bars on the scales. Default is True.

 ShowAutoScaleButton - In the open view, controls visibility of the Auto Scale Button. Default is False.

 EditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use ShowTracesLegend and ShowScalesLegend to control visibility of the trace(s) and scale(s) names.

GridType: - Default is Lines. Shows lines at the major divisions and tic marks at the minor divisions. The X and Y axes are shown as thick lines.

Smith Chart - Displays data in a Smith Chart (also called an "impedance chart"). Marker values are given as real and imaginary impedances. The bold circle is the "reference radius" and its linear radius value is shown in the lower right corner of the display. The Smith Chart grid and markers only represent properly scaled values if the input data has been normalized. To normalize the data, divide all magnitudes by the characteristic impedance.

Inv Smith Chart - Displays data in an Inverse Smith Chart (also called an "admittance chart"). An Inverse Smith Chart is used in the same way as a Smith Chart except grid and marker values are admittance values rather than impedance values.

NumMarkers: - The number of markers defined for the graph. To move markers to a different trace, go to the open view and click on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

MarkerInterpolate - When the property is True, >/font> you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

DisplayBackColor: - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view.

Traces Group: (one per trace)

Name: - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Color: - The color of the trace. Each added trace has a different color than the existing traces. Default for the first trace is yellow.

LineStyle: - The format of the line connecting data points. Default is a continuous line.

PointStyle: - The symbol that marks each data point. To show unconnected data points, select the single dot LineStyle format and the desired PointStyle symbol. Default is a dot.

Scale - If it exists for more than one Y scale, choose which scale this Trace is scaled by.

Scales property: (one per X and Y scale and extra Y scales)

Show Scale: - If you have multiple Radius scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name: - The names of the scales appearing in the open view.

Automatic Scaling: - Controls whether the display automatically rescales to show the entire trace immediately after it receives data. Default is True. If this is turned False, you can rescale the display by using the Auto Scale button on the General tab, in the Layout group, or the AutoScale command on the object menu.

Vertical Span: - The vertical dimension of the display. The default value is 2.

Scale Color - The color of any background grid or tic marks. Default is Gray.

Reference Corner: - Specifies the part of the polar plot displayed. This is quicker than scrolling to the area. Changing the Reference Value scrolls the part of the graph specified (such as Center) to the location specified (such as (0, @0)). The default value is Center.

Reference Value: - Defines the numeric polar coordinate values to be used in the polar plot. The default values are (0, @0).

Notes

Inputs must be of the type Spectrum, Waveform, or Coord (Scalar or Array 1D).

Input data of type Coord is plotted by simply using its x and y values as rectangular coordinates without first being converted to type Spectrum.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

When the Automatic Scaling property is on (Scales tab), the program executes faster if a complete set of data is sent to the display. Then, the display automatically rescales once. If a program sends one data point at a time to the display, the display may automatically rescale after each data point, which will slow down program execution. In this case, use a Collector object to create an array, then send the array to the display.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A Text field named Scale with a value X, Y (or Y1), Y2, or Y3. The Scale field is required. An error occurs if it is omitted.

One or more of the following fields:

Name - Changes the scale name in the open view. Must be a text value.

Min - Sets the X scale minimum. Must be an integer or real value.

Max - Sets the X scale maximum. Must be an integer or real value.

Mapping - Must have a text value of Linear or Log.

AutoScale - Controls automatic scaling. Must have a text value of On or Off.

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties dialog box. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers group. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display’s Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the display's Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] Spectrum (Freq) [image] Magnitude vs Phase (Polar)

Display [image] Spectrum (Freq) [image] Magnitude vs Phase (Smith)

See Also

Magnitude Spectrum, Phase Spectrum, Polar Plot, Spectrum (Freq), and Default Preferences.

To Display a Waveform, To Set Markers in the Display, To Get and Set Marker Properties, and Object Menu


Main

Main is the root UserObject window in VEE.

Use

The Main window is the root UserObject in VEE programs. It is required in programs and cannot be deleted. Other UserObject and UserFunction windows are created from the Main window.

If the Main window has been minimized or closed, it can be re-opened by selecting it from the View menu. It can also be reopened by clicking on Main in the VEE Program Explorer window.

Properties

Title - Displays the current title of the program. You can edit the title when an object is placed in the panel view. The title is displayed in the title bar of the program when the program is run with the -r command-line option. The default is Untitled.

ShowPanelonExecute: - This property is available when you add an object to the Main panel view. When ShowPanelonExecute is on, the Main panel view appears in the Execution window when you run the program.

TrigMode group:

Degrees | Radians | Gradians - specifies the trigonometric units used in the main program. If you select Radians, your trigonometric calculations will execute the fastest. The Trig Mode used by UserObjects is not affected by this setting.

Convert Infinity to 9.9E37 on Binary Reads - If the check box is selected, when an instrument (or a file containing instrument data) returns +INF (+infinity), -INF (-infinity), or NAN (not a number) on a binary read, VEE converts it. This conversion will slow down I/O somewhat on every binary read.

You may want to select the check box if you're getting data from an instrument that follows the SCPI standard and you're outputting that data to a graphical display object. If the check box is not selected, and +INF, -INF, or NAN is sent to a display object, you will get a floating-point exception error. If the check box is selected, you'll be aware of the +INF, -INF, or NAN value by a spike in the graph.

Notes

If the Main window has not been closed, it will also appear in the Window menu as:

Window [image] 1 Main

Location

View [image] Main

See Also

Arrange Icons, Cascade, Close All, Minimize All, Program Explorer, Tile Horizontally, Tile Vertically, and Properties (Object)


Make UserFunction (Object menu)

A menu selection, found only in the object menu for a UserObject, which converts the UserObject into a UserFunction.

Use

Use Make UserFunction to convert a UserObject into a UserFunction. The name displayed in the title area of the UserObject becomes the UserFunction name. The UserObject disappears and is replaced with a Call Function object.

Notes

If the name in the UserObject title area is not a valid name for a UserFunction, or if you haven't changed the name from "UserObject", you will be prompted for a new name for the UserObject.

A valid UserFunction name must begin with an alpha character, followed by alphanumeric characters or underscores.

Location

On the object menu (UserObjects only) [image] Make UserFunction

See Also

Call, Edit UserFunction, hidePanel(), showPanel(), UserFunction, and UserObject.


Make UserObject

A menu selection, found only under Edit UserFunction, which re-converts a UserFunction back into a UserObject.

Use

Use Make UserObject to convert a UserFunction back into a UserObject.

Notes

Make UserObject is almost the inverse of Make UserFunction. Although Make UserObject converts the UserFunction back into a UserObject, any Call Function objects remain present, and remain connected in the main context of the program. However, the UserFunction itself is gone.

Location

Edit [image] Edit UserFunction [image] Make UserObject (on the UserFunction Object Menu)

See Also

Edit UserFunction, Make UserFunction (Object menu), UserFunction, and UserObject.


math_syntax

This list contains links to the Help topics for VEE math operators and functions.

abs(x)
acos(x)
acosh(x)
acot(x)
acoth(x)
a + b (add)
Ai(x)
a ~= b (almost equal to)
a AND b
+ - * /
Array
asin(x)
asinh(x)
atan(x)
atan2(y,x)
atanh(x)
bartlet(x)
Bessel
beta(x,y)
Bi(x)
binomial(a,b)
bit(x,n)
bitAnd(x,y)
bitCmpl(x)
bitOr(x,y)
bits(str)
bitShift(x,y)
Bitwise
bitXor(x,y)
blackman(x)
Calculus
ceil(x)
charToInt(a)
clearBit(x,n)
clipLower (x,a)
clipUpper (x,a)
cofactor(x, row,col)
comb(n,r)
Comma Operator
Complex Parts
concat(x,y)
conj(x)
convolve(a,b)
cos(x)
cosh(x)
cot(x)
coth(x)
cubert(x)
Data Filtering
defIntegral (x,a,b)
deriv(x, order)
derivAt(x, order,pt)
det(x)
a div b (truncated division)
a / b (divide)
dmyToDate (d,m,y)
a == b (equal to)
erf(x)
erfc(x)
exp(x)
exp10(x)
a ^ b (exponent)
exponential regression
factorial(n)
fft(x)
floor(x)
fracPart(x)
Freq Distribution
gamma(x)
Generate
a > b (greater than)
a >= b (greater than or equal to)
hamming(x)
hanning(x)
hmsToHour (h,m,s)
hmsToSec (h,m,s)
Hyper Bessel
Hyper Trig
i0(x)
i1(x)
identity(x)
ifft(x)
im(x)
init(x,val)
integral(x)
intPart(x)
intToChar(a)
inverse(x)
j(x)
j0(x)
j1(x)
jn(x,n)
k0(x)
k1(x)
a < b (less than)
a <= b (less than or equal to)
linear regression
log(x)
log10(x)
logarithmic regression
Logical
logMagDist (x,from,thru, logStep)
logRamp (numElem, from,thru)
mag(x)
magDist(x, from,thru, step)
matDivide (numer, denom)
matMultiply (A,B)
Matrix
max(x)
maxIndex(x)
maxX(x)
mday(aDate)
mean(x)
meanSmooth (x,numPts)
median(x)
min(x)
minIndex(x)
minor(x,row, col)
minX(x)
a mod b (modulo)
mode(x)
month(aDate)
movingAvg (x,numPts)
a * b (multiply)
NOT a
a != b (not equal to)
now()
a OR b
ordinal(x)
perm(n,r)
phase(x)
poly(x,vec)
Polynomial
polynomial regression
polySmooth (x)
Power
power curve regression
product(x)
ramp (numElem, from,thru)
random (low,high)
randomize (x,low,high)
randomSeed (seed)
re(x)
Real Parts
recip(x)
rect(x)
Regression
rms(x)
rotate(x, numElem)
round(x)
sdev(x)
setBit(x,n)
Signal Processing
signof(x)
sin(x)
sinh(x)
sort(x, direction, field)
sq(x)
sqrt(x)
Statistics
strDown(str)
strFromLen (str,from,len)
strFromThru (str,from, thru)
String
strLen(str)
strPosChar (str,char)
strPosStr (str1,str2)
strRev(str)
strTrim (str,trimlist)
strUp(str)
a - b (subtract)
sum(x)
tan(x)
tanh(x)
Time & Date
totSize(x)
transpose(x)
Triadic Operator
Trig
vari(x)
wday(aDate)
xcorrelate (a,b)
xlogRamp (numElem, from,thru)
a XOR b
xramp (numElem, from,thru)
y0(x)
y1(x)
year(aDate)
yn(x,n)


MATLAB® Script

An object that calls the MATLAB Script engine with operations specified by MATLAB Script commands. VEE data can be passed to the MATLAB Script engine and returned from the MATLAB Script engine.

MATLAB Help

The Help topic you are reading describes how to invoke MATLAB from VEE. It does not explain how to write MATLAB programs or what you can do with MATLAB once you have invoked it. Help on MATLAB and its scripting language is available two ways:

VEE’s Function & Object Browser has a Help button at the bottom. Clicking the Help button when you have a MATLAB function selected starts the MATLAB Help system and displays the topic for that function.

The MATLAB object menu (right-click menu) contains a MATLAB Help choice. (Note: "Help" and "MATLAB Help" are both on this menu.) Clicking MATLAB Help starts the MATLAB Help system.

If your MATLAB Script object was created from VEE’s Device menu, the help system is started with the main MATLAB HelpDesk window. If your MATLAB Script object was created from VEE’s Function & Object Browser, the help system is started with the topic for the function you selected when you created the MATLAB Script object.

Use

Use the MATLAB Script object to access the power of MATLAB software within VEE. This object is similar to a VEE Formula object. MATLAB Script commands can be entered in the formula field, and data can be passed using input and output pins.

Many predefined functions are available when you create a MATLAB Script object from the Function & Object Browser. Alternately, the default object available from the Device menu has two inputs, one output, and an example script (X=A+B). Any of these example objects can be modified to have a different number of input or output pins and a different set of MATLAB Script commands. There are approximately 1800 functions available in the MATLAB Script engine supplied with VEE. The MATLAB Signal Processing Toolkit provides about 220 more functions. VEE's Function & Object Browser shows more than 1100 of the most popular functions. Consult the MATLAB HelpDesk for information about all the MATLAB functions.

Variable names in MATLAB Script are case sensitive, but not so in VEE. In other words, "A" and "a" refer to the same variable in VEE, but refer to different variables in MATLAB. Keep this in mind when writing formulas in MATLAB Script. For example, if your VEE data terminal is named "A", use "A" in the MATLAB Script, not "a".

VEE does not perform any syntax checking of MATLAB Script commands. If your MATLAB Script object contains syntax errors, those errors are not discovered until the MATLAB Script engine is called. Any errors reported by MATLAB are mapped to VEE errors 591 or 592. If MATLAB reports any warnings, these are shown as VEE Caution messages.

The first MATLAB Script object to execute opens a single MATLAB session. All other instances of MATLAB Script objects share that same session. Therefore, MATLAB Script objects can share global variables in the MATLAB workspace.

MATLAB Script, as provided by this VEE object, does not support the MATLAB function definition capability.

Data Notes

Only some VEE data types are allowed as MATLAB Script inputs. You can use input terminal data type constraints to ensure that VEE input data is converted to a supported type. For example, assume you have Int32 data. The MATLAB Script object does not accept integer data, but it accepts Real64 data. You can double-click the input terminal and select Real64 as the Required Type. With that constraint set, inbound Int32 data is automatically promoted to Real64 by the input pin before it is passed to MATLAB. VEE also provides some automatic array conversions to increase the convenience of using VEE 1D arrays. The following tables describe the alignment of VEE data types and MATLAB data types.

Input Pin Data

From VEE Type | To MATLAB Type | Notes
Text Scalar | character array | Promoted to array size (1 x n), where n is the length of the VEE string.
Text 1D Array | character array | Becomes array size (m x n), where m is the number of elements in the VEE array and n is the length of the longest VEE string in the array.
Text Array, 2D or more | -- | Not supported.
Real64 Scalar | double array | Promoted to array size (1 x1).
Real64 Array | double array | VEE 1D arrays are promoted to array size (m x 1). VEE arrays with 2D or greater retain original shape.
Complex Scalar | complex array | Promoted to array size (1 x 1).
Complex Array | complex array | VEE 1D arrays are promoted to array size (m x 1). VEE arrays with 2D or greater retain original shape.
Waveform 1D Array | double array | VEE 1D arrays are promoted to array size (m x 1). Waveform time-base mapping is lost.

Output Pin Data

From MATLAB Type | To VEE Type | Notes
Empty Matrix | nil | No output container is generated.
character array of size (1 x n) | Text Scalar |
character array of size (m x n) | Text 1D Array | Shaped as 1D array with m elements.
character array, 3D-10D | -- | Not supported.
double array of size (1 x 1) | Rea64 Scalar |
double array of size (m x 1) or (1 x n) | Real64 1D Array or Real64 2D Array | Automatic demotion to VEE 1D array is selectable in object properties. Otherwise, a 2D array is returned.
double array, 2D-10D | Real64 Array |
complex array of size (1 x 1) | Complex Scalar |
complex array of size (m x 1) or (1 x n) | Complex 1D Array or Complex 2D Array | Automatic demotion to VEE 1D array is selectable in object properties. Otherwise, a 2D array is returned.
complex array, 2D-10D | Complex Array |

MATLAB Script allows (and sometimes generates) infinity as a numeric value. VEE does not allow values of infinity. If a MATLAB Script object attempts to return the floating-point representation for plus infinity, minus infinity, or NaN (not a number), the call will fail and generate VEE error 594.

Multiple MATLAB Versions

If you have one or more MATLAB versions installed on your machine, then you can easily choose one to use in Agilent VEE. Refer to Choose a MATLAB to use in VEE for further information.

MATLAB 5.3, 6.1, 6.5, 7.x ( includes R2006a, 2006b, 2007a ) all work under VEE 8.5.

Location

Device [image] Function & Object Browser [image] MATLAB Functions

Device [image] MATLAB Script

See Also

MATLAB Script Overview, MATLAB FAQ


Merge

Adds the contents of a program or set of saved objects into the work area while keeping the existing contents of the work area.

Use

Use Merge to combine a previously saved program or set of objects into an existing program in the VEE work area. Merge is useful for bringing in previously created programs or sets of objects from a library of functions that are used often.

Notes

Any Default Preferences (for example, the Trig Mode) that are saved with a program will not be loaded or used when you Merge that program into the VEE work area. The currently active Default Preferences for the work area will remain unchanged.

You cannot use Merge for UserFunctions. Use Merge Library instead.

Merge presents a dialog box that lets you select the name of the file you want to open. When you use Merge, the dialog box points to the lib directory under the VEE program installation directory.

You use Merge to load a file that was saved with Save or Save As.

If the program saved has a panel view, the panel is not imported into the program. The panel views of UserObject are input.

Doing a Merge from a program file containing an embedded I/O configuration does not merge any of that I/O configuration. See Embedded I/O Configurations and Merging.

Location

File [image] Merge

See Also

Merge Library, Open, Save, and Save Objects.

To Create a Library of UserObjects

To Merge Objects and Programs from Library Files


Merge Library

Loads a library of UserFunctions into the work area.

Use

Use Merge Library to merge UserFunctions previously saved in a library file of functions, into the current work area.

Merge Library loads all of the UserFunctions from a specified file. (UserFunctions are created by selecting the Make UserFunction selection on the object menu of a UserObject. You create a library by creating several UserFunctions and saving them to a file.)

Once the library of UserFunctions is loaded, the functions are executed (called) by name using the Call object.

Notes

Merge Library is used for advanced operations where you have developed sets of UserFunctions into libraries. When you develop a library of UserFunctions, you can keep the source code for those functions in a single place. Refer to Help [image] Content [image] Tell me about... User-Defined Functions for a detailed discussion of using UserFunctions.

UserFunctions loaded by Merge Library operate exactly like any locally-created UserFunction within the program. You can execute any UserFunction with the Call object, or by including the UserFunction in any object that takes an expression (for example, Formula). You can edit any of the merged UserFunctions, loaded by Merge Library, as they are now merged into the VEE work area.

Any Default Preferences (for example, the Trig Mode) that are saved with a function will not be loaded or used. The currently active Default Preferences for the work area will remain unchanged.

Merge Library presents a dialog box that allows you to select the name of the file you wish to open. The dialog box points to the lib directory under the VEE program installation directory.

Doing a Merge Library from a program file containing an embedded I/O configuration does not merge any of that I/O configuration. See Embedded I/O Configurations and Merging.

Location

File [image] Merge Library

See Also

Call, Delete Library, Edit UserFunction, Import Library, Open, Save, Save Objects, UserFunction, and UserObject.


Merge Record

An object that allows the user to merge two or more records of the same shape into a single record.

Use

Use Merge Record to merge two or more records into a single record. Any number of scalar records can be merged. Any number of record arrays can be merged so long as all arrays have the same number of elements.

Notes

Any number of input pins (A, B, and so forth) may be added, but each must be of the Record data type. The merged record is output on the Record output pin.

The records to be merged must not have any duplicate field names. The field names are taken from the input records (the input terminal names are ignored).

Location

Data [image] Access Record [image] Merge Record

See Also

Build Record, From DataSet, Record Constant, Set Field, To DataSet, UnBuild Record, and Properties (Object)


Message Box

An object that displays a pop-up dialog box that contains a message to the user.

Use

Use Message Box to display an informational message to the user. The user responds by pressing one of the buttons on the dialog box. The text on the buttons may be customized.

In the pop-up dialog box, when a button is pressed, a 1 is output on the output pin associated with (having the same name as) the button.

Open View

  • Message - The string of information displayed on the Message Box pop-up dialog box. Use \n to start a new line in the text in this field. You may add this parameter as a data input. Default is User Message

  • Symbol - The graphical image displayed on the left side of the Message Box pop-up dialog box. You may add this parameter as a data input.

    • Question - A white question mark within a green circle.

    • Exclamation - A black exclamation mark within a yellow circle.

    • Information - A white letter "i" within a blue circle.

    • Stop - A white text "STOP" within a red hexagon.

    • Blank - Use this when you do not want a graphic on the pop-up.

    • <Custom...> - Gives you a dialog box allowing you to select a picture from graphics files to use as your symbol.
      In the dialog box:
      - Picture - Enter the file name of a graphics file from your file system. The directory shown is the bitmaps directory under the installation directory. To choose a file from another directory, press the Browse... button.
      - Actual (default) automatically resizes the object to fit the graphic image's actual size.
      The image does not scale if the object is resized. - Scaled rescales the graphic image's size as the object is resized.

You may add this parameter as a data input. Default is Information

  • Buttons - The text shown on the buttons displayed at the bottom of the Message Box pop-up dialog box. Choices are

  • OK

    • OK Cancel

  • Abort Retry Ignore

    • Yes No

    • Yes No Cancel

    • Retry Cancel

    • <Custom ...> - Gives you a dialog box in which to input text for the button labels for up to three buttons. If you leave an input field blank, you will not get a button for that field.

The data output pins are automatically configured to correspond to your choice for Buttons.

  • Default - The button that is selected when the user presses Enter. The choices displayed depend on the Buttons chosen. You may add this parameter as a data input. Default is OK.

Properties

  • PopupTimeoutEnabled - When this property is True, a Timeout output pin is added to the object. Default is False.

  • PopUpDuration - Sets the length of time the pop-up dialog box is displayed. After this period of time, the dialog box times out and a value of 1 is output on the Timeout output pin. No other outputs pins have data if the Timeout pin executes. This field is only available when the Timeout Enabled check box is selected. Default is 60 seconds.

Notes

The default location of the pop-up dialog box is approximately at the center of the work area. If you move it, next time it will pop-up to the new location.

To respond to the pop-up dialog box using only the keyboard: when the dialog box pops up, use the Enter key to select the leftmost button and the Esc key to select the rightmost button. Or use the Tab key to move between the buttons and select the buttons with the Space bar.

The pop-up dialog box is only displayed while the program is running. While the pop-up dialog box is displayed, the entire program pauses execution, then continues when the dialog box is closed.

If you added a Timeout output pin to the object by turning on Timeout Enabled in Properties on the General tab, you can delete it only by turning off Timeout Enabled. You cannot delete this output pin using Delete Terminal on the object menu, or Ctrl+D (the "delete terminal" shortcut).

Location

Data [image] Dialog Box [image] Message Box

See Also

File Name Selection, List Box, Int32 Input, Real64 Input, Text Input, UserObject. and Object Menu

About Built-In Dialog Box Objects


Meter

An object that graphically displays a Scalar numeric value.

Use

Use Meter to display a value on an analog scale and digital numeric field.

Open View

The minimum and maximum values of the Meter are set on the open view of the object by clicking on the present value and typing in a new value. If minimum value is greater than the maximum value, the Meter needle's operation direction is changed (i.e., right to left instead of left to right).

These values may also be added as control inputs.

Properties

ClearAtPreRun - When the property is True, the contents of the Meter are cleared at PreRun. Default is True.

 ClearAtActivate - When the property is True, the contents of the Meter are cleared at Activate. Default is True.

Orientation - Sets how the Meter is displayed. If the orientation of the Meter is vertical, the minimum value is at the top and the maximum is at the bottom. Default is Horizontal.

 ShowDigitalDisplay - If the property is True, a digital display of the displayed value is added to the bottom of the open view of the object. If the property is False, the digital display is not displayed and the object operates faster. Default is True.

 ShowTics - Controls visibility of scale’s tic marks and labels. Default is True.

 Logarithmic - When the property is True, changes scale from linear to logarithmic. Default is False.

 LabelSpacing - Controls which tic marks are labeled with the scale values. Default is Every Other Tic.

Sub-Range Configuration Category: - Sets different colors for different ranges of the display. The color ranges overlay each other with red on the bottom and green on top. This allows red (default) sub-ranges at each end of the scale.

Show Range - When the property is True, the sub-range color is displayed on the object.

Meter Range - Sets the limits of the sub-range.

ColorRange - Sets the color for the different ranges

NumberFormat:

Global Format - Use the default format. Default is True.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

The input data must be Scalar and able to be converted to Real64 (Complex, PComplex, Spectrum, and Coord must be first "unbuilt".)

Location

Display [image] Indicator [image] Meter

See Also

AlphaNumeric, Logging AlphaNumeric, and Default Preferences.

To Show an Analog Display of Data


Minimize All

A function for managing windows in the VEE workspace.

Use

Minimize All will minimize all opened, non-minimized windows. Minimized windows will appear as small icons at the bottom of the VEE workspace.

Location

Window [image] Minimize All

See Also

Arrange Icons, Cascade, Close All, Tile Horizontally, and Tile Vertically.


Minimize (Object Menu)

Iconizes the open view of an object or window.

Use

Use Minimize to show the icon view of an object or to minimize an open window (Main, UserObject, UserFunction) in the VEE work space.

Notes

Minimize is available from the open view of all objects and windows.

Short Cuts

To minimize an object or window, press the minimize button on the upper right of the object or window (on the right side of the title bar).

Location

On the object menu [image] Minimize

See Also

Restore (Object Menu).


Miscellaneous Operators

A Formula type object found under Function & Object Browser.

Use

Generally, you can use the Miscellaneous Operators objects to access the Triadic Operator, to create or read simple arrays, or to read a field in a record.

Notes

When you have selected Operator => Miscellaneous in the Function & Object Browser tool window will display a variety of operator examples. Clicking on one of these examples will bring up a VEE object pre-loaded with that Miscellaneous Operator. The example objects include:

(a?b:c) - A triadic operator. If 'a' is true (non-zero), then 'b' is output, else 'c' is output.

PI - The value 3.14 (carried out 17 decimal places). A transcendental number represented by the ratio of the circumference to the diameter of a circle.

[1,2,3] - Create a 1-dimensional array from scalars.

[a,b,c] - Create an array of any dimension from matching-shape parts.

a[2] - Return part of an array.

a[5,3:4,*] - Return part of a more complex array.

rec.field - Return one field of a record.

object.value - Get a Property of an ActiveX object.

Location

Device [image] Function & Object Browser [image]  Operators [image] Miscellaneous

See Also

Assignment, Function & Object Browser, and Triadic Operator


Move (Object Menu)

Moves this object.

Use

Use Move to reposition the object on the work area by dragging it.

Notes

Move retains the connections with other objects. If Automatic Line Routing is set, it may take a few moments to redraw lines.

Move works in both Panel and Detail view.

To move multiple objects, select the objects (using CTRL-left mouse button or Edit [image] Select All) and drag them.

You may also select multiple objects to move by drawing a rectangle around the objects them. You can accomplish this by placing your mouse in the upper left corner of the area you are selecting and then, with the CTRL key and your left mouse key depressed, drag to the lower right corner of the selection area.

If moving causes Objects to overlap in Panel view, use Bring to Front or Send to Back from the Object Menu to adjust the positioning of the Objects.

Short Cuts

Instead of selecting Move, place your cursor over the object. This activates the four-corner move cursor. Drag the object (using the left mouse button). The pointer must not be over an action area of the object (like a button or an entry field).

Location

On each object menu [image] Move

See Also

Object Menu.


Move File

Move a file from a given location to a new location. You may also rename a file using this same process.

Location

System [image] File [image] Move File


MultiDevice Direct I/O

An object that writes data to and reads data from more than one instrument in the same transaction box.

Use

Use MultiDevice Direct I/O to output and input a variety of encodings and formats to instruments at various I/O addresses.

Open View Parameters

The open view shows the list of transactions to be executed.

Direct I/O Actions:

READ: Reads data from an instrument using the specified encoding and format.

WRITE: Writes data to an instrument using the specified encoding and format.

EXECUTE: For a GPIB instrument, sends either a Selected Device Clear, Go To Local, Remote, or Group Execute Trigger command. For a serial instrument, sends Break or Reset. For a GPIO instrument, sends Reset. For a VXI message-based instrument, sends either a Selected Device Clear, Go To Local, Remote, Trigger, Lock Device, or Unlock Device command.

WAIT: Waits the specific number of seconds before executing the next transaction. For a GPIB instrument or a VXI message-based instrument, wait until the bitwise AND of the serial poll response with the mask is either zero (ALL CLEAR) or non-zero (ANY SET).

For GPIO instruments only, the READ action allows IOSTATUS and the WRITE action allows IOCTL.

For VXI instruments only, the READ and WRITE action allows REGISTER: and MEMORY:. The WAIT action also supports the ability to wait until the value in a memory or register offset AND a mask value satisfy the ANYSET, ALL CLEAR, or EQUAL.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Short Cuts

You can quickly add a data terminal by placing the cursor over the input or output terminal display area and then pressing CTRL+A. Each press of CTRL+A adds an additional data terminal.

You can quickly delete a data terminal by placing the cursor over the terminal view area and then pressing CTRL+D.

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To paste a transaction from the "kill" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Notes

MultiDevice Direct I/O is very similar to Direct I/O. However, MultiDevice Direct I/O is not dedicated to any specific instrument. Each transaction can communicate with any configured instrument at various I/O addresses. The transaction dialog box lets you specify the intended instrument from the available configured instruments.

You can use an instrument's default address originally entered during instrument configuration, or specify another address. In cases where an instrument address is different, click on the Default Address button to reveal an additional text box. Enter the new address value or variable name in the box.

Location

I/O [image] Advanced I/O [image] MultiDevice Direct I/O

See Also

Advanced I/O, Component Driver, Direct I/O, Formula, Instrument Manager, Panel Driver, and To/From VXIplug&play.

To Read Data Using Direct I/O

To Use a Direct I/O Object

Properties (Object)

Using the MultiInstrument Direct I/O Object

To Edit a Transaction


New

Clears the work area.

Use

Use New to clear the work area.

Notes

If your program has not been saved, New prompts you to save your changes.

New does not clear the Paste buffer. New reads in the default Preferences settings from the defaults file, VEE.RC.

New maintains the directory paths that the Save and Open commands use.

Short Cuts

Press CTRL+N to clear the program.

Location

File [image] New

See Also

Default Preferences


Next

An object that causes a Repeat [image] object to immediately start the next iteration.

Use

Use Next to skip to the next iteration of the current loop without executing the remaining objects on the iteration subthread.

If Next is not on an iteration subthread, it stops all execution on the subthread.

Notes

Next is often used with an If/Then object to conditionally control iteration.

Location

Flow [image] Repeat [image] Next

See Also

Break, For Count, For Log Range, For Range, If/Then/Else, On Cycle, and Until Break.

To Loop Part of a VEE Program

Properties (Object)


NI-FGEN

While using NI-FGEN in VEE, several transactions cause the creation of a “handle”. Some of these are:

  • AGniFgen_CreateFreqList

  • AGniFgen_CreateWaveformF64

  • AGniFgen_CreateWaveformI16

  • AGniFgen_CreateWaveformFileI16

  • AGniFgen_CreateWaveformFileF64

  • AGniFgen_CreateWaveformFileHWS

  • AGniFgen_CreateArbSequence

  • AGniFgen_CreateAdvancedArbSequence

  • AGniFgen_AllocateWaveform

These handles are returned from the transaction by way of an output pin and can be passed around to other objects in your program. They can also be used internally by other transactions inside the same To/From NI-FGEN Object. It is important to remember to “Clear” the Sequence/Waveform/Frequency-List handle that was created by one of the above transactions when you are finished with its output generation. For each of the above transactions, there is a corresponding “Clear” transaction which takes the handle as an input pin. Example:

Notice the “AGniFgen_AbortGeneration” transaction before the “AGniFgen_ClearFreqList”.

See Also

To/From NIDAQ, NI-SCOPE Fetch/Read Functions, NI-DAQmx, Using NI Data Acquisition in VEE


NI-SCOPE Fetch/Read Functions

Certain NI-SCOPE functions that return waveform data, do so in a manner inconsistent with VEE’s capabilities. VEE cannot handle pointers to structures. These functions:

  • AGniScope_Fetch

  • AGniScope_FetchArrayMeasurement

  • AGniScope_FetchBinary8

  • AGniScope_FetchBinary16

  • AGniScope_FetchBinary32

  • AGniScope_Read

Differ slightly from their descriptions in the National Instruments On-line Help for NI-SCOPE. First, VEE only allows for Fetching/Reading a single channel at a time. If a multi-channel acquisition was set up by the user, they will have to do multiple Fetches/Reads to get each individual channel’s data one channel at a time. Secondly, instead of returning a pointer to the niScope_wfmInfo structure which contains the following fields:

wfmInfo

struct niScope_wfmInfo

Returns an array of structures with the following timing and scaling information about each waveform:

  • relativeInitialX - the time (in seconds) from the trigger to the first sample in the fetched waveform

  • absoluteInitialX - timestamp (in seconds) of the first fetched sample that is comparable between records and acquisitions; your digitizer must support continuous acquisition

  • xIncrement - the time between points in the acquired waveform in seconds

  • actualSamples - the actual number of samples fetched and placed in the waveform array

  • gain - the gain factor of the given channel; useful for scaling binary data with this formula

  • offset - the offset factor of the given channel; useful for scaling binary data with this formula

voltage = binary data * gain factor + offset

VEE returns ViReal64 relativeInitialX and ViReal64 xIncrement as separate parameter values. If the user needs access to absoluteInitialX, actualSamples, gain, or offset, they can call AGniScope_GetAttributeViReal64 () with the appropriate Attribute ID. The values returned by VEE can be used to create a VEE waveform in this manner:

The above VEE program also demonstrates a multi-fetch two-channel acquisition.

See Also

To/From NIDAQ, NI-FGEN, NI-DAQmx, Using NI Data Acquisition in VEE


Noise Generator

An object that generates a waveform of noise data.

Use

Use Noise Generator to generate a waveform of simulated white noise.

Open View Parameters

All of these parameters may be set from the open view or added as data inputs.

Amplitude - The absolute value of the maximum and minimum values. Default is 1. No value is greater than Amplitude. No value is less than -Amplitude.

Time Span: - The duration of the waveform (in seconds) Default is 20m.

Num Points: - The number of points in the waveform. The time between points in the waveform is Time Span/N. Num Points must be positive. Default is 256.

Location

Device [image] Virtual Source [image] Noise Generator

See Also

Build Arb Waveform, Build Waveform, Comparator, Function Generator, Pulse Generator, and Properties (Object)


Note Pad

Displays an editable Rich Text Format (RTF) dialog box that displays user-supplied information. There is a default NotePad entry, which demonstrates the capabilities of the dialog box, that is displayed when the NotePad dialog box is opened. To create your own default NotePad entry, edit the notepad.rtf file in installdir\templates. If you want an empty NotePad dialog box, edit the notepad.rtf file and leave it empty or delete the file altogether.

Use

Use Note Pad to document your program, label the panel view, or write notes.

Open View Parameters

To enter information in the Note Pad, click on the panel, then type the note, or type the text in any RTF enabled application then cut and paste it into the Note Pad.

Object Menu

Insert File... - Gives you a dialog box that lets you select an existing text or RTF file to insert into Note Pad.

Clear All - Clears all text from Note Pad, with a dialog box to confirm or reject the action.

Properties

EditingEnabled - When this property is True, allows you to edit the text in the panel. When not selected, no editing is allowed. This is useful when a Note Pad is on a panel view and you don't want other users to modify your note.

Notes

Each Note Pad is a stand-alone object and is not connected to any other objects.

After editing or resizing, scroll bars are added or removed from the Note Pad as required.

You can use all the usual VEE edit functions to edit the text area.

Notepad is in Rich Text Format (RTF) with word wrap enabled. You can cut and paste any RTF document into Notepad.

You can print the Notepad text, but it is always in pure text format.

You can create a template for your Notepad entries by editing the Notepad.rtf file found in %installDir%\Templates.

Location

Display [image] Note Pad

See Also

Description

To Document Your Program


Now (System Menu)

Now

Retrieves the system time and date.

Location

System [image] DateTime [image] Now


Object Menu

The menu associated with every object that contains selections that affect that object.

Use

Use the object to set status, edit, set controls, and add and delete the terminals of an object.

Use Object Menu to access the following object actions:

Restore

Move

Size

Minimize

Clone

Replace

Help

Properties

Description

Add Terminal

Data Input

Control Input

Data Output

Error Output

Delete Terminal

Input

Output

Delete

Use the Object Menu to access the following actions for objects placed on the panel views of the Main window, UserObjects, or UserFunctions:

Move

Size

Properties…

Go To Detail View

Delete

Notes

Many object menus have additional menu features specific to that object. Refer to information on the object for details about those object menu choices.

Most objects have additional options specific to that object on their Properties window. Refer to information on the object for details about those object properties.

Short Cuts

To delete an object, double-click on the object menu button (available in the open view).

To access the Properties window, double-click on the object's title bar (available in the open view).

To get help on a selected object, press F1.

Location

To access an object's Object Menu, position the pointer over the object and click the right mouse button. Note that to access the object menu of the open view of a UserObject you must position the pointer over the title bar or terminals, otherwise, the Edit Menu is presented.

You can also access the Object Menu from the open view by positioning the pointer over the object menu button (the square with a bar in the middle to the left of the title bar) and pressing the left mouse button.

See Also

Move (Object Menu), Size (Object Menu), Minimize (Object Menu), Restore (Object Menu), Replace, Clone (Object Menu), Help (Object Menu), Properties (Object), Description, Add Terminal, Delete Terminal, Control Input (Object Menu), Data Input (Object Menu), Data Output (Object Menu), Error Output (Object Menu), and Cut (Object Menu).


OK

An object that pauses the execution flow of a subthread until it is pressed.

Use

Use OK to wait for a user response.

Properties

Assign to Function Key - When the property is True, this object will execute when the specified function key is pressed from the detail view or the panel view. You can assign a function key to multiple OK objects. Default is False.

Assign to Enter Button - When the property is True and the program is being run from the panel view, pressing Enter on your keyboard will execute the object. You can have only one OK assigned to Enter per context. If you try to set it for more than one OK, the previous setting is unselected. This property is useful when you use an OK object as the OK button on a custom dialog box. Default is False.

 Assign to Escape Button - When the property is True and the program is being run from the panel view, pressing the Esc key on your keyboard will execute the object. You can have only one OK assigned to Esc per context. If you try to set it for more than one OK, the previous setting is unselected. This property is useful when you use an OK object as the Cancel button on a custom dialog box. Default is False.

Notes

OK often is used when creating a dialog box or with the Selection Control constant.

The button part of the OK doesn't become active until the object operates.

You can use either the Go data output pin or the sequence output pin to continue the thread.

Another way to pause the execution flow of a thread when using objects under Data [image] Constant is to use the Wait for Input property.

Location

Flow [image] Confirm (OK)

See Also

Gate, JCT, Start, Stop, and Object Menu

To Assign a Button to a Function Key

To Assign an OK Button to the Enter or Esc Key

To Build a Basic Dialog Box

To Keep a Pop-Up Panel Displayed


On Cycle

An object that begins execution of a subthread at a specified interval.

Use

Use On Cycle to execute a subthread that must be repeated periodically. The output of On Cycle is the current date and time. This date and time can be displayed on any object that supports a Time Stamp number format.

Use On Cycle to trigger instruments at specific intervals.

Open View Parameters

Enter the number of seconds per iteration period in the entry field or as an input. If this value is 0 or -1, On Cycle operates continuously (the same as Until Break).

Notes

Execution of the subthread hosted by the On Cycle output continues until one of the following occurs:

All objects that can, have operated. The subthread is deactivated, the iteration timer is reset, and the subthread is reactivated after the number of seconds have elapsed.

A Break object operates. The subthread is deactivated and the sequence output pin is activated.

A Next object operates. The subthread is deactivated and the iteration timer is reset.

On Cycle starts operation at the specified time period. If the thread takes longer to complete than the period of the On Cycle object, then the next iteration starts at the next period synchronization point. For example, if the period in the On Cycle is 1 second and the thread it hosts takes 1.5 seconds to complete, the next iteration starts .5 seconds after the thread completes.

While waiting for the next time period to begin, On Cycle "sleeps" allowing other objects on this or other threads to operate.

When the subthread hosted by the On Cycle object finishes an iteration, all data containers sent during the previous iteration are invalidated before the next iteration. This prevents "old" data from a previous iteration from being reused in the current iteration. However, if flow branching is present within the iterative subthread, some objects may not execute on every iteration. Thus, data containers sent by those objects may be invalidated before other objects can execute on the data. To obtain the desired propagation in this case, use the Sample & Hold object.

Location

Flow [image] Repeat [image] On Cycle

See Also

AlphaNumeric, Break, For Count, For Log Range, For Range, Next, Sample & Hold, Until Break, and Properties (Object)

To Loop Part of a VEE Program


Open

Loads a program file into the work area, replacing the existing program.

Use

Use Open to bring a previously saved program into VEE for running or editing. Move to the directory where the file is located, click on the file name, and press OK. The program is displayed on your screen.

Notes

Open presents a dialog box that allows you to select the name of the program file you wish to open. When VEE is loading in the file, the pointer icon changes to a pair of glasses.

You can Open a file that was saved with Save Objects, Save or Save As.

Short Cuts

CTRL+O opens files.

Location

File [image] Open

See Also

Merge, Save, and Save Objects.

To Open a VEE Program File


OS Version

Retrieves the operating system version of the host system.

Location

System [image] Environment [image] OS Version


Output Window

Output window logs Warning and Error messages that occur when you are loading, writing, debugging, and running an Agilent VEE program.

Window Information

Output pane list

There are two output panes to choose. General pane is used to display Warning and Error messages that occur when you are loading or writing programs. All warning and error messages generated when debugging or running programs will be logged in the Debug pane.

Caution message in the Output pane takes the format:

CAUTION> Source: VEE object type (object ID) Message: message

COMPILER WARNING> Source: VEE object type (object ID) Message: message

Double clicking on a compiler warning in the Output window will bring the VEE object that causes the warning into view in the work space.

Error message in the Output pane takes the format:

Error> Number: n Source: VEE object type (object ID) Message: message

Double clicking on an error in the Output window will bring the VEE object that causes the error into view in the work space.

Output pane

Displays the output for the selected pane in the output pane list.

To clear messages in the current Output pane, click [image] button. VEE will clear Output pane automatically when you create a new program or open an existing program.

Location

From the Main Menu View => Output

From Toolbar click

See Also

To Arrange and Dock Tool Windows


Pad Left

Pads the left side of the string with the character you designate.

Location

System [image] String [image] Pad Left


Pad Right

Pads the right side of the string with the character you designate.

Location

System [image] String [image] Pad Right


Panel Driver

An instrument control object that forces all the function settings in the corresponding physical instrument to match the settings in the control panel displayed in the open view of the object.

Use

Use a Panel Driver to control the state of an instrument by means of the control panel displayed in the open view. Before you can use a Panel Driver, the instrument driver for the desired instrument must be installed.

To add a Panel Driver object to the VEE work area, click on I/O [image] Instrument Manager to display the Instrument Manager dialog box. Check the list of configured instruments to see if there is an entry for the instrument you want to use:

If the instrument you want is in the list, and is properly configured:

1. Click once on the instrument entry to highlight it.

2. Click on Panel Driver to add the instrument panel for that instrument.

If the instrument you want is not in the list, or is in the list but not properly configured, it needs to be added and/or configured. Refer to Instrument Manager, Instrument Properties, and Advanced Instrument Properties.

For further information about using Panel Drivers, refer to Help [image] Content [image] Tell me about... Instrument Control Fundamentals [image] Introduction to Panel Drivers and Component Drivers.

Object Menu

Add Terminal by Component [image] Select Input Component - Use to add fields visible on the panel as inputs to a Panel Driver.

Add Terminal by Component [image] Select Output Component - Use to add fields visible on the panel as outputs to a Panel Driver.

Show Config - Displays the configuration of an instrument. (You can edit this configuration using I/O [image] Instrument Manager.)

Sync - Synchronizes an instrument driver's state to the state of the instrument under the following conditions:

The ID code contains a sync component.

The ID has live mode turned on.

Notes

Panel Drivers may be operated with Live Mode off. This allows you to run your program without communicating with the instrument, even if the instrument is not connected to the computer. This means that you must set Live Mode to on (refer to Advanced Instrument Properties) before your program will communicate with the physical instrument.

Panel Drivers can be used interactively or within a program. To set the value of an individual component, click on the field containing the value of the component and complete the resulting dialog box. To make a measurement and display the result, click on the corresponding numeric readout or XY display inside the Panel Driver open view.

It is possible to have more than one object controlling a single instrument. That is, two Panel Driver objects could control fgen in the same program. These objects perform state recalls when operated.

You can add inputs and outputs for the components of a Panel Driver (just as for a Component Driver). Inputs perform the set actions, panel set actions, and coupled actions for the component. Control pins are available as inputs to initialize the instrument, programmatically change the instrument address and timeout period, and for a sync signal. Outputs perform the get actions and panel get actions.

Location

I/O [image] Instrument Manager

See Also

Advanced Instrument Properties, Add Terminal, Component Driver, Direct I/O, Instrument Manager, Instrument Properties, and To/From VXIplug&play.

To Read Data with a Panel Driver Object


Paste

Places a copy of the Paste buffer on the work area.

Use

After using Cut, Copy, or Clone on the Detail view, use Paste to retrieve a copy of a set of objects.

Paste allows you to recover objects that have been accidentally Cut. Connections to and from these objects are also restored.

Notes

The Paste buffer only holds one set of objects. The Paste buffer is replaced each time you Clone, Cut or Copy.

The Paste buffer is not cleared when you use Open, Merge, or New.

Paste does not paste text - only objects. Use keyboard keys to cut/copy and paste text. Highlight the text, then use Ctrl-C (copy) or Ctrl-X (cut), then click in the new location and use Ctrl-V (paste).

Location

Edit [image] Paste

See Also

Clone (Object Menu), Copy, Cut, Cut (Object Menu), and Replace.


Pause

A button that temporarily causes all threads to stop running.

Use

Use Pause to temporarily suspend program execution. After Pause is selected, select Resume to continue execution.

Notes

Selecting Pause puts the program in the "paused" state. Both Resume and the Step functions are active and can be used to proceed.

Short Cuts

Press CTRL+P to pause a running program.

Location

Debug [image] Pause

See Also

Call Stack, Line Probe, Default Preferences, Run/Resume, Run, Show Data Flow, Show Execution Flow, Step Into, Step Over, Step Out, Stop, Stop (Object), and Toggle Breakpoint.

To Step through a Program


PComplex

An object that outputs a constant PComplex scalar or 1D Array.

Use

Use PComplex to set a Polar Complex constant or to get user input. Click on the entry field to enter a value.

Example

To use PComplex as a prompt on a panel view, change the name of the PComplex object to a prompt such as Enter the AC voltage:. The user fills in the requested information in the entry field.

Type in (2,@PI/2) and it will calculate the PComplex Constant formula.

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are scalar and Array 1D.

 ArraySize: - When DataShape 1D Array is selected, Size sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D Array is selected.

 ShowArrayIndices - When the property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is False.

Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

 InitialValue - Specifies the value to be set. Default value is (0, @0).

 InitializeAtPreRun - When the property is True, the Initial Value is set at PreRun time. Default is False.

 InitializeAtActivate - When the property is True, the Initial Value is set at Activate time. Default is False.

NumberFormat: Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires a PComplex value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the Initial Value field is always a scalar, even if the PComplex is configured to be an array.

Trig Mode specifies phase value units. Trig mode can be set globally or on each context (UserObject and UserFunction)

You can enter Magnitude and Phase values (separated by commas) and VEE formats automatically.

Location

Data [image] Constant [image] PComplex

See Also

Alloc PComplex, Complex, Constant, Coord, Date/Time, Selection Control, UInt8, UInt16, Int16, Int32, Int64, Real32, Real64, Text, Boolean, Default Preferences, and Toggle Control.

To Use a Data Constant


Phase Spectrum

An object that graphically displays the magnitude of a spectrum as a function of its phase angle.

Use

Use Phase Spectrum to display phase against frequency of Spectrums or Waveforms (in the frequency domain). Waveforms are automatically converted to spectrums by way of a Fourier Transform. The X axis is in the sampling units of the input spectrum. The Y axis units are the current Trig Mode setting.

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Phase - The name of the Y axis.

Trace1 - The name of the first trace.

Freq - The name of the X axis.

Object Menu

Auto Scale [image] - Clicking these menu items immediately rescales the display to show the entire trace. (Can be added as control pins, or set using the Scales properties tab to automatically rescale the display after data is collected.)

Auto Scale - Automatically scales both axes.

Auto Scale X - Automatically scales the X axis.

Auto Scale Y - Automatically scales the Y axis.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets the display to show the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Y-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints or plots a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When the property is True, the display is cleared at PreRun time. Default is True.

 ClearAtActivate - When the property is True, the display is cleared at Activate time. Default is True.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EditTracesAndScales to control the edit-button function of the trace legends. Default is True.

 ShowScalesLegend - In the open view, controls visibility of the scale names. Use EditTracesAndScales to control the edit-button function of the scale legends. Default is True.

 ShowScaleLabels - In the open view, controls visibility of the values labeling the scale axes. Default is True.

 ShowScrollBars - In the open view, controls visibility of the scroll bars on the X and Y scales. Default is True.

 Show AutoScaleButton - In the open view, controls visibility of the Auto Scale Button. Default is False.

 EditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use ShowTracesLegend and ShowScalesLegend to control visibility of the trace(s) and scale(s) names.

GridType - Lines. Shows lines at the major divisions and tic marks at the minor divisions. The X and Y axes are shown as thick lines.

Markers Category: - Allows you to find the exact value of a data point on the displayed curve. If the data is plotted on a log scale, the values shown on the marker are the linear data points.

To move markers to a different trace, go to the open view and click on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

 NumMarkers - The number of markers shown in the graph. The None selection is the default.

 MarkerInterpolate - When the property is True, you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

DisplayBackColor - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view.

ScaleLabelFont - Allows you to select the font of the scale labels from the list of available fonts on your system. The default font for scale label text is set in Default Preferences on the Fonts tab for Screen Element: Graph Scale Label Text.

Traces group: (one per trace)

Name - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Color - The color of the trace. Each added trace has a different color than the existing traces. Default for the first trace is yellow.

LineStyle - The format of the line connecting data points. Default is a continuous line.

PointStyle - The symbol that marks each data point. To show unconnected data points, select the single dot LineStyle format and the desired PointStyle symbol. Default is a dot.

Scale - If it exists for more than one Y scale, choose which scale this Trace is scaled by.

Scales property: (one per X and Y scale and extra Y scales)

Show Scale: - If you have multiple Y scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name: - The names of the scales appearing in the open view.

Automatic Scaling: - Controls whether the display automatically rescales to show the entire trace immediately after it receives data. Default is on. If this is turned off, you can rescale the display by using the Auto Scale button on the General tab, in the Layout group, or the Auto Scale command on the object menu.

Maximum: - The maximum values of the scales.

Minimum: - The minimum values of the scales.

Label Spacing: - Controls which tic marks are labeled with the scale values. Default for X scale is Every Other Tic; default for Y scale(s) is Every Major Tic.

Mapping: - The way the x and y data is mapped to the display. The mapping may be linear or log. To make a log-log plot, change both X and Y axes to Log. Default is Linear.

Log Cycles: - The maximum number of decades shown (counting down from the maximum x and y values) when Automatic Scaling is on. Log Cycles is only used when the Mapping is Log. Log Cycles is useful when a trace contains a large dynamic range in the data. Default is 4.

Scale Color - The color of any background grid or tic marks. Default is Gray.

ScaleNumberFormat: (a property appears for the X and Y scales, and for any additional Y scales.)

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

The X and Y marker values take on the same number format as the scale to which they are attached. The delta marker values for X and Y use the default number format unless you use the Time Stamp format. Then, if both markers 1 and 2 on the X scale, or both markers on the Y scale are using the Time Stamp format, the delta marker values use the Delta Time format.

Notes

Inputs must be of the type Spectrum, Waveform, or Coord (Scalar or Array 1D).

Input data of type Coord is plotted by simply using its x and y values without first being converted to type Spectrum.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

When the AutomaticScaling property is True (Sc ales category), the program executes faster if a complete set of data is sent to the display. Then, the display automatically rescales once. If a program sends one data point at a time to the display, the display may automatically rescale after each data point, which will slow down program execution. In this case, use a Collector object to create an array, then send the array to the display.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A Text field named Scale with a value X, Y (or Y1), Y2, or Y3. The Scale field is required. An error occurs if it is omitted.

One or more of the following fields:

Name - Changes the scale name in the open view. Must be a text value.

Min - Sets the X scale minimum. Must be an integer or real value.

Max - Sets the X scale maximum. Must be an integer or real value.

Mapping - Must have a text value of Linear or Log.

AutoScale - Controls automatic scaling. Must have a text value of On or Off.

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties window. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers group. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display's Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the display's Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] Spectrum (Freq) [image] Phase Spectrum

See Also

Magnitude Spectrum, Magnitude vs Phase, Spectrum (Freq), Default Preferences, and Object Menu

To Display a Waveform, To Set Markers in the Display, To Get and Set Marker Properties


Picture

An object that is used to display a graphic image.

Use

Use Picture to display a graphic image on the Detail or Panel View. It allows you to tile, stretch, and clip your picture. The graphics file name may be added as a data input to the Picture object.

Properties

Picture Category:

Use Picture to choose a graphics file from your file system to be displayed on this object. The directory shown is the bitmaps directory under the installation directory. To choose a file from another directory, press the Browse ... button. You may add the file name as a data input.

Actual | Centered | Scaled | Tiled
-- Select Actual to specify automatic resizing of the object to fit the actual size of the graphic image. If the object is resized, the image does not scale, and is displayed in the upper left corner of the object.
-- Select Centered to specify that the image is kept fixed size and always centered on the object, even if the size of the object is changed.
-- Select Scaled to specify that the image is scaled as the size of the object is changed. Rescaling may take a few moments to complete.
-- Select Tiled to duplicate the image horizontally and vertically on the object to create a "wallpaper" effect.

Preview - Displays the current graphic image selected.

VEE examines the file to determine the file format. The currently supported formats are:

Bitmaps (*.BMP)

JPEG (*.JPG)

Windows Meta File (*.WMF)

GIF87a (*.GIF)

GIF89 (*.GIF)

Portable Network Graphics (*.PNG)

Default bitmaps are located in the bitmaps directory under the VEE program installation directory.

Notes

If the size property is set to a choice other than Actual, the default background color for the object is the same as the default Panel View color so that the background blends into the Panel View.

A background graphic can be added to any UserObject or UserFunction panel, as well as having Picture objects on their panels.

GIF89 support is limited to a single frame (no animated GIFs), and a transparent background color is not allowed.

Location

Display [image] Picture

See Also

Label, Beep, and UserObject.

To Add a Picture to the Panel


Plug&play Device Configuration

Allows you to specify or modify the configuration for a Plug&play instrument to be used from VEE

Use

Use this dialog box to add or edit instruments from the list of configured instruments.

Note that not all Plug&play drivers support all platforms. Also, certain versions of VTL/VISA may not be supported on all platforms. Please check with the appropriate vendor.

Dialog Information

The Plug&play Driver tab of the Advanced Instrument Properties dialog box is divided into these areas:

Plug&play Driver Name: - Select the name of the driver. The selections available are the drivers which have been installed. This is also the directory where the driver is located. This field is required. The default location of these drivers are:

C:\program files\VISA\WINNT

Parameters to init() call

Address: - Enter the digits of the address that identifies the instrument. The address format depends on the interface that the instrument is connected to:

- VXI address string. For a VXI instrument with an embedded or MXIbus controller, the address string takes the form VXI[board]::VXI logical address[::INSTR]. An example is VXI::24::INSTR for an instrument at logical address 24.

- GPIB-VXI address string. For a VXI instrument that is being controlled from a GPIB card to a command module, the address string takes the form GPIB-VXI[board]::VXI logical address[::INSTR] . An example is GPIB-VXI0::24::INSTR for an instrument at VXI logical address 24.

- GPIB address string. For a non-VXI instrument being controlled from a GPIB card, the address string takes the form GPIB[board]::GPIB primary address::[GPIB secondary address][::INSTR] An example is GPIB0::4::24::INSTR for an instrument at primary address 4 and secondary address 24.

Perform Identification Query - When the check box is selected, the identity of the instrument is checked the first time a function panel for this driver is executed. Generally, you want to select this check box.

Perform Reset - When the check box is selected, the instrument is initialized to a pre-defined state the first time a function panel for this driver is executed. Generally, you want to select this check box.

Notes

The Plug&play Driver Name field allows you to select the driver name from those drivers that have already been installed. To install the set of files needed for each driver, follow the instructions included with the instrument driver. Each VXIplug&play driver was written by the hardware vendor and shipped with the instrument.

It is possible to have more than one object controlling a single instrument. It is also possible to have multiple copies of the same driver, each controlling a different physical instrument. In either case, it is the configured name that determines which object controls which instrument.

Location

I/O [image] Instrument Manager. Then press the Add… or Properties button to display the Instrument Properties dialog box. Press the Advanced button.

See Also

Direct I/O, Instrument Manager, Instrument Properties, Panel Driver, and To/From VXIplug&play.


Polar Plot

An object that displays a graphical plot in polar coordinates.

Use

Use Polar Plot to display a value on a polar scale when separate polar information is available for radius and angle data.

When more than one trace is to be plotted, each execution of the Polar Plot object uses the single angle input data with each trace's Radius input data, therefore, all traces share the single angle input.

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Y name - The name of the radius scale.

Span: - The vertical dimension of the display. When the origin is centered on the display, the Span is twice the radius. This parameter controls the scaling of the display. Default is 2.

RData1 - The name of the first trace.

Polar Reference Location - Specifies the part of the polar plot displayed. This is quicker than scrolling to the area. Changing the reference point in the entry field scrolls the point of the display specified (such as Center) to the coordinate specified (such as (0,@0)).

Ref Radius: - The radius value of the bold graticule circle.

Object Menu

Auto Scale [image] Auto Scale - Immediately rescales the display to show the entire trace. Auto Scale resets the polar reference location to Center (0,@0). (Can be added as a control pin, or set using the Scales properties tab to automatically rescale the display after data is collected.)

Auto Scale X - Not available.

Auto Scale Y - Not available.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets to display to show the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input. The Next Curve Control Pin is not allowed with Matrix-Input graphs, see Matrix-Input graphs.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Radius-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints or plots a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When the property is True, the display is cleared at PreRun time. Default is True.

 ClearAtActivate - When the property is True, the display is cleared at Activate time. Default is True.

MatrixInput - When this property is True, the Polar Plot would accept a 2D Array (up to a max of 255 rows) as Input data and display multiple traces at the same time. APolar Plot object is called a Matrix-Input graph if it's MatrixInput property is set to True.

This MatrixInput property can be set to True only if there is no Next Curve Control Pin and the Polar Plot has one single input data pin. Similarly, additional data inputs cannot be added to Matrix-Input graphs.

The MatrixInput property is not available in Panel View, and cannot be toggled at runtime programmatically.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EnableEditTracesAndScales to control the edit-button function of the trace legends. Default is True.

 ShowScalesLegend - In the open view, controls visibility of the scale names. Use EnableEditTracesAndScales to control the edit-button function of the scale legends. Default is True.

 ShowScrollBars - In the open view, controls visibility of the scroll bars on the scales. Default is True.

 ShowAutoScaleButton - In the open view, controls visibility of the Auto Scale Button. Default is False.

 EnableEditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use ShowTracesLegend and ShowScalesLegend to control visibility of the trace(s) and scale(s) names.

GridType - Default is Lines.

Smith Chart - Displays data in a Smith Chart (also called an "impedance chart"). Marker values are given as real and imaginary impedances. The bold circle is the "reference radius" and its linear radius value is shown in the lower right corner of the display. The Smith Chart grid and markers only represent properly scaled values if the input data has been normalized. To normalize the data, divide all magnitudes by the characteristic impedance.

Inv Smith Chart - Displays data in an Inverse Smith Chart (also called an "admittance chart"). An Inverse Smith Chart is used in the same way as a Smith Chart except grid and marker values are admittance values rather than impedance values.

Markers Category: - Allows you to find the exact value of a data point on the displayed curve. If the data is plotted on a log scale, the values shown on the marker are the linear data points.

To move markers to a different trace, click on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

NumMarkers - The number of markers on the graph.

MarkerInterpolate - When this property is set to True, you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

BackColor - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view.

Traces Group: (one per trace)

Name: - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Color: - The color of the trace. Each added trace has a different color than the existing traces. Default is yellow.

LineStyle: - The format of the line connecting data points. Default is a continuous line.

PointStyle: - The symbol that marks each data point. To show unconnected data points, select the single dot LineStyle format and the desired PointStyle symbol. Default is a dot.

Scales: - If it exists for more than one Y scale, choose which scale this Trace is scaled by.

Scales property: (one per X and Y scale and extra Y scales)

Show Scale: - If you have multiple Radius scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name: - The names of the scales appearing in the open view.

Automatic Scaling: - Controls whether the display automatically rescales to show the entire trace immediately after it receives data. Default is on. If this is turned off, you can rescale the display by using the Auto Scale button on the General tab, in the Layout group, or the Auto Scale command on the object menu.

Vertical Span: - The vertical dimension of the display. The default value is 2.

Scale Color - The color of any background grid or tic marks. Default is Gray.

Reference Corner: - Specifies the part of the polar plot displayed. This is quicker than scrolling to the area. Changing the Reference Value scrolls the part of the graph specified (such as Center) to the location specified (such as (0, @0)). The default value is Center.

Reference Value: - Defines the numeric polar coordinate values to be used in the polar plot. The default values are (0,@0).

Notes

When the MatrixInput property is False, Inputs must be Scalar or Array 1Ds that can be converted to the type Real64.

When the MatrixInput property is True, Polar Plot can accept a 2D Array (up to a max of 255 rows) as Input data and display multiple traces at the same time.

Angle units are in the current Trig Mode.

All inputs must be the same size and shape. Mapping information on the inputs data is ignored.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

When the Automatic Scaling property is on (Scales tab), the program executes faster if a complete set of data is sent to the display. Then, the display automatically rescales once. If a program sends one data point at a time to the display, the display may automatically rescale after each data point, which will slow down program execution. In this case, use a Collector object to create an array, then send the array to the display.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have:

One or more of the following fields:

Name, Name1, Name2, and/or Name3 - Must be a text value.

Span, Span1, Span2, and/or Span3 - Must be an integer or real value.

RefPt - Must be a PComplex

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties dialog box. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers group. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display’s Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the display's Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] Polar Plot

See Also

Complex Plane, Magnitude Spectrum, Magnitude vs Phase, Spectrum (Freq), Strip Chart, Waveform (Time), and Default Preferences.

To Display Polar Data, To Set Markers in the Display, To Get and Set Marker Properties


Pop-Up List

See Selection Control.


Print

A dialog box that allows you to print using standard Microsoft Windows printing conventions.

Use

Use the Print dialog box to select the print quality and number of copies to print.

Dialog Information

Printer - Identifies the current Windows system printer. To change the printer, click on the Properties button to display the Print Setup dialog box.

Print Range - Fixed at All for VEE.

Print Quality - Selections are printer specific. For HP LaserJet Printers, it defaults to 300 dpi (300 dots-per-inch).

Copies - Enter the number of copies to print (default = 1).

Collate Copies - Defaults to off (no checkmark). Click on the check box to turn Collate Copies on.

When you are done, click on OK if you are ready to print or Cancel to stop without printing. Or, click on Properties if you want to display the Print Setup dialog box, which allows you to change additional parameters.

Notes

Refer to your Microsoft Windows documentation for further information about setting up printers for Windows applications.

Location

File [image] Print Screen

File [image] Print Program

File [image] Print Objects

See Also

Print Objects, Print Program, Print Screen, and Print Setup.

To Change the Printing Preferences

To Print a VEE Program

To Print Objects in a VEE Program

To Print or Copy the VEE Window

To Print the VEE Work Space


Print Objects

Outputs a page for each of the selected objects, containing all views and Description data, to a printer or a print file.

Use

Use Print Objects to get hardcopy of selected objects. Print Objects displays a dialog box that specifies information about the printer configuration.

Print Objects will print all views (icon, open, detail, or panel), along with Description data, for each object. If the object contains transactions, the detailed dialog box describing each transaction is also printed.

If no objects are currently selected, the Print Objects menu item will be grayed out.

Dialog Information

Print Objects displays the appropriate dialog box for your system; see Print.

Notes

Print Objects may take a few moments to capture the image of the objects, particularly if you select a large number of objects. While the image is being captured, the pointer changes to an hourglass. You can't use VEE until the capture is completed (the pointer changes back to an arrow).

VEE saves only one configuration for printing, which stays constant from one printing operation to the next.

Location

File [image] Print Objects

See Also

Print, Print Program, Print Screen, Default Preferences, and Select All.

To Change the Printing Preferences

To Print a VEE Program

To Print Objects in a VEE Program

To Print or Copy the VEE Window

To Print the VEE Work Space


Print Program

Outputs the entire detail view of the program to a printer or a print file.

Use

Use Print Program to get hardcopy of your entire program. Print Program displays the Print Options dialog box that allows you to specify what to output to the printer. After you have selected your print options, clicking on the OK button will bring up the Print dialog box.

Print Program produces indexed pages to show the complete structure of a VEE program. The output includes a total view of the top-level program, and a page for each object in the program, which shows all views of the object and its Description data. If the object contains transactions, the detailed dialog box describing the transaction is also printed. Each page of the output contains information describing the image's place in the program.

Various aspects of the printing process may be controlled independently by way of the Print Options dialog box.

Dialog Information

The Print Program dialog box displays five fields:

Print Nested UserObjects - Causes the print engine to recursively print any nested UserObjects that are within the object that is currently being printed.

Print Object Views - Causes all objects within a context to be printed. However, how an object is printed is somewhat dependent on an object's complexity. That is, simple objects, such as a Gate, a Junction, or an UntilBreak object, are printed as they would appear in the VEE program. More complex objects, such as a Graph or Sequencer object, will be printed in its open view form.

Print Header and Index Page - If this box is checked, each page of the VEE program printout will contain a two-line header which shows the date, time, program file name, and a page number. At the end of the printout, an index page will be printed which shows the page numbers of the indexed items.

Print Program Explorer - When this box is checked, the VEE program printout will show the information contained in the Program Explorer window.

Print Cover Page - When this box is checked, the first page of the VEE program printout will show the following:

A graphic of the VEE product logo.

The file name of the program being printed.

The file format under which the program was saved.

The revision code of the VEE software being used (such as 6.0, etc.).

The current VEE execution mode (VEE 6, VEE 5, etc.).

Print I/O Configuration - When this box is checked, the instrument configuration’s expanded tree view is printed. You can see the instrument configuration in I/O [image] Instrument Manager…

When you press OK, the appropriate dialog box appears for your system; see Print.

Notes

Print Program takes a few moments to capture the image of your program. While the image is being captured, the pointer changes to an hourglass. You can't use VEE until the capture is completed (the pointer changes back to an arrow).

VEE saves only one configuration for printing, which stays constant from one printing operation to the next.

Location

File [image] Print Program...

See Also

Default Preferences, Print, Print Screen, Print Objects, and Save Documentation.

To Change the Printing Preferences

To Print a VEE Program

To Print Objects in a VEE Program

To Print or Copy the VEE Window

To Print the VEE Work Space


Print Screen

Outputs the contents of the VEE window to a printer or a print file.

Use

Use Print Screen to get hardcopy of the portion of your program that is visible on your screen. Print Screen displays a dialog box that specifies information about the printer configuration.

Dialog Information

Print Screen displays the appropriate dialog box for your system; see Print.

Notes

Print Screen takes a few moments to capture the image in the window. While the image is being captured, the pointer changes to an hourglass. You can't use VEE until the capture is completed (the pointer changes back to an arrow).

The size of the VEE display window determines the size of the print area. To get a large output, maximize the VEE window (but too large an image gets clipped). Larger images take longer to scan and print.

VEE saves only one configuration for printing, which stays constant from one printing operation to the next.

Location

File [image] Print Screen

See Also

Print, Print Program, Print Objects, and Default Preferences.

To Change the Printing Preferences

To Print a VEE Program

To Print Objects in a VEE Program

To Print or Copy the VEE Window

To Print the VEE Work Space


Print Screen Object

An object that prints a copy of the visible portion of the VEE window on the system printer.

Use

Use Print Screen to print a copy of the visible work area while the program is running.

Notes

The printer used by Print Screen (the VEE system printer) is configured by:

File [image] Print Setup

Print Screen directs output to the configured graphics printer or directory.

A running program is paused when Print Screen operates. It resumes when Print Screen is finished.

Location

I/O [image] Print Screen

See Also

Print, Print Program, Print Screen, Print Objects, and Default Preferences.

To Change the Printing Preferences


Print Setup

A dialog box that allows you to set up your printer using standard Microsoft Windows printing conventions.

Use

Use the Print Setup dialog box to select a printer, the printing orientation, and the paper size and source.

Dialog Information

Printer - Select either Default Printer or Specific Printer. If you select Specific Printer, you can select from a list of printers configured on your Windows system.

Paper - Select the paper Size and Source from the lists of supported choices.

Orientation - Select either Portrait or Landscape.

If you click on Properties, an additional (the standard Windows) dialog box prompts you for further selections.

Notes

Refer to your Microsoft Windows documentation for further information about setting up printers for Windows applications.

When running VEE under Windows XP, Send True Type as Bitmaps should be On in the Document Properties dialog box. This dialog box is accessed from File [image] Print Setup. In the Print Setup dialog box, click the Properties button, then click details... button under the Finishing tab.

Location

File [image] Print Setup

(Or select one of the other print options from the file menu to bring up the Print dialog box.)

See Also

Print, Print Program, Print Objects, and Print Screen.

To Change the Printing Preferences

To Print a VEE Program

To Print Objects in a VEE Program

To Print or Copy the VEE Window

To Print the VEE Work Space


Profiler

A menu choice that provides you with execution information regarding UserObjects and UserFunctions.

Use

When you enable the Profiler, the Profiler tool window will appear. From the Profiler tool window you can profile a variety of execution parameters for each UserObject and UserFunction in a VEE program.

When the Profiler is started, it will provide you with comparative information regarding the amount of time each UserObject or each UserFunction is taking to execute. This information may be very useful when you are attempting to modify your VEE program to maximize efficiency, and improve execution speed.

As long as the Profiler is enabled, PROF will be highlighted on the program Status Bar in the lower right corner of the VEE workspace.

Window Information

The Profiler tool window contains a toolbar and a profiler Result pane.

Profiler Result Pane

Name - The Name column lists the name of each UserObject and each UserFunction being profiled.

# Executions - This column shows the number of times each UserObject or UserFunction executed during profiling.

% Time - Shows the total percentage of time, within the context of the entire program execution, that a particular UserObject or UserFunction spent executing.

Time(sec) - Shows the amount of time, in seconds, that a particular UserObject or UserFunction took to execute.

Profiler Toolbar

Start Profiling - The Start Profiling button will Start Profiling. When profiling has been started, the PROF field will be highlighted on the VEE program Status Bar.

Stop Profiling - The Stop Profiling will Stop Profiling. When profiling has been stopped, the PROF field will be greyed out on the VEE program Status Bar.

Refresh - The Profile Information dialog box does not automatically update with new profile data. You must click on the Refresh button to cause the Profiler to retrieve the latest profile data from the running, paused or stopped VEE program.

Clear - The Clear button resets all field values in the Profiler Information dialog box to 0 (zero).

Save - Clicking on the Save button will cause the Profiler data to be saved to a file name you can specify using the Options... button. (See the Options... explanation below).

Options... - Clicking on the Options... button will bring up the Profiler Options dialog box. The Profiler Options dialog box contains the following fields and buttons:

# digits for % Time - This field allows you to specify how many digits of accuracy (to the right of the decimal point) you want to have displayed in the % Time field on the Profiler tool window. The default number of digits is 2.

# digits for Time(sec) - This field allows you to specify how many digits of accuracy (to the right of the decimal point) you want to have displayed in the Time(sec) field on the Profiler tool window. The default number of digits is 3.

Show only executed contexts - If this box checked (enabled), Profiler data will be shown only on those UserObjects and UserFunctions that executed. By default, this box is not checked.

Save Options group - The items in the Save Options group define options about how Profiler data are saved to a data file. These options are:

- Save File Name: - This field specifies the file name where Profiler data is saved. Clicking on this field will bring up the Save data filename dialog box. From the Save data filename dialog box, you can specify the file name and file type you wish to use to store the Profiler data. The default file name is profile.dat.
- Overwrite data - If the Overwrite data box is checked (enabled), each time you Save newly collected Profiler data, you will overwrite the Profiler data previously collected and saved to the Profiler data file. By default, Overwrite data is enabled.
- Comma delimited - The Comma delimited box allows you to specify whether or not Profiler data is written to the data file in comma delimited format or non-comma delimited format. If the data is written in Comma delimited format, data is written to the data file with commas as delimiters (separators) between the various Profiler data fields. Using comma delimiters in the data file makes it much easier to transfer the data file to other types of software applications (such as spreadsheets). By default, the Comma delimited box is not checked (not enabled).
- OK - Clicking on OK to confirm any options you have selected in the Profiler Options dialog box.

Help - Clicking on the Help button brings up the help topic related to the Profiler.

Notes

After the Profiler has collected and displayed data in the Profiler tool window, you can double click on any UserObject or UserFunction shown in the Name field, and that UserObject or UserFunction will be brought into the VEE workspace.

Additionally, clicking on any column labels such as Name, # Executions, % Time, etc., will cause the data displayed in the Profiler tool window to be sorted in reverse order. Clicking again will reverse the sort again.

Location

View [image] Profiler

See Also

Call Stack, Clean Up Lines, Show Data Flow, Show Execution Flow, and Properties (Object).

To Profile Execution Parameters


Program Explorer

A View menu item that opens the Program Explorer tool window.

Use

To open the Program Explorer tool window, click the View [image] Program Explorer or the toolbar button [image].

The Program Explorer tool window is a tool window. Refer to To Arrange and Dock Tool Windows for more information on how to dock, hide, float it.

Notes

The purpose of the Program Explorer window is to show the programmer the hierarchical structure of the VEE program that is currently loaded. This structure is shown using different icons to represent different parts of the program. The icons represent complete lists of the following different types of program information:

UserObject hierarchies starting at the Main UserObject.

Local UserFunction list.

Imported UserFunction library list and associated functions.

Imported Compiled Libraries and associated functions.

Imported Remote UserFunction Libraries and associated functions.

Globals, both declared and undeclared.

Declared library globals under the appropriate library.

Declared local variables under the appropriate context.

A large portion of the Program Explorer functionality is accessed through context menus. For example, if you move the mouse cursor over a UserObject icon in the Program Explorer window and then click the right mouse button, the context menu for a UserObject will appear.

Not all items in Program Explorer will provide a context menu, but the menus that do appear will depend on the type of item (a UserObject icon, a UserFunction icon, etc.). The following items in Program Explorer will provide context menus:

Program (or Root) Node

Main UserObject

UserObjects

UserFunctions

Local UserFunctions

Imported UserFunctions

Imported UserFunction Library

Remote UserFunction

Compiled Function

Global Variable

Library Global Variable

Local Variable

Location

View [image] Program Explorer

See Also

Default Preferences, UserFunction, UserObject

To Explore the Program Structure


Properties (Object)

The Window associated with every object containing selections that affect that object. This page describes only the general properties that are available on every object. Due to the characteristics of some objects, certain options and tabs are not available.

Use

Use the Properties Window to edit the title, set a breakpoint, set object colors and fonts, set title colors and fonts, change the appearance of the icon and the open view, and perform other object-specific actions.

Window Information

Title - Displays the current title of the object and allows you to edit it.

 ShowTitleBar - When this property is True, the title bar on the open view of the object is displayed.

 Show Terminals - When this property is True, Show Terminals displays the input and output terminals on the open view. The displayed terminals show the terminal name. To access complete terminal information, double-click on the object's terminal.

BreakpointEnabled - Enables the breakpoint on the object when the property is True; disables the breakpoint on the object when the property is False. Use BreakpointEnabled as a debugging tool to pause the execution of the program before this object executes. The object that is next to execute has a yellow border (by default). To continue execution, press the Resume or one of the Step buttons on the tool bar. When a breakpoint is set in the Properties window or selected from the Debug menu, the breakpoint is enabled and the object is highlighted with a orange (by default) border.

 Title BackColor - Allows you to select the color of the title bar (open view) and the title (icon view) from a palette.

 Title ForeColor - Allows you to select the color of the text used in the title bar (open view) and the title (icon view) from a palette.

 BackColor - Allows you to select the color of the open view of the object from a palette.

 ForeColor - Allows you to select the color of the text used in the open view from a palette. This choice is not available if there is no text in the body of the open view of the object.

 Title Font - Allows you to select the font of the title bar (open view) and the title (icon view) from the list of available fonts on your system.

 Font - Allows you to select the font of the text used in the open view from the list of available fonts on your system. This choice is not available if there is no text in the body of the open view of the object.

ShowIconTitle - When the this is True, the object name on the icon view of the object is displayed. When Show Title is False, the object name is not displayed on the icon. This feature is generally used if you want only a bitmap to be displayed on the icon.

IconPicture - Use Picture to choose a graphics file from your file system to be displayed on this icon.

The directory shown is the bitmaps directory under the installation directory. To choose a file from another directory, press the Browse ... button.

Select Centered to specify that the image is kept fixed size and always centered in the icon, even if the size of the icon is changed.

Select Scaled to specify that the image is scaled as the size of the icon is changed.

Preview - Displays the current graphic image selected. See Help on the Picture object for currently supported formats.

Default bitmaps are located in the bitmaps directory under the VEE program installation directory.

Border: available only from objects on the Panel view

None | Flat | Sunken | Raised - Select the border characteristics of the object displayed on the panel.

Location: available only from objects on the Panel view

X: - The horizontal location (in pixels) of the upper left corner of the object. 0 is located at the upper left of the work area.

Y: - The vertical location (in pixels) of the upper left corner of the object. 0 is located at the upper left of the work area.

Size: available only from objects on the Panel view

Width: - The distance between the left and right sides of the object. This number includes the width of any object border.

Height: - The distance between the top and bottom sides of the object. This number includes the width of any object border.

Notes

When modifying a Font property, the font Dialog has a checkbox labeled Automatically Resize Object on Font Change. When the check box is selected, you've changed a font, and pressed OK, the object resizes to fit the new font. When the check box is not selected, the object remains the same size, no matter how large or small the font is. This choice is not available if there is no Object Text font selection.

Any changes you make in the Properties window from the panel view of the object, only affect the panel view of that object. The Properties choices available from the panel view of an object are a subset of the detail view choices.

Most objects have additional options specific to that object in their Properties window (which is accessed via Properties on the object menu). Refer to information on that object for details about those object properties.

Short Cuts

You can quickly access the Properties window by double-clicking on the object's title bar (available in the open view).

Location

On each object menu [image] Properties ...

From the Main Menu View [image] Properties

See Also

Default Preferences and Object Menu


Pulse Generator

An object that generates and outputs a pulse waveform.

Use

Use Pulse Generator to generate a pulse waveform using your own specifications.

Properties

ErroronAliasing - If the property is True, returns an error if the period of any high or low pulse state is less than twice the sampling period (Time Span/Num Points). The purpose of this evaluation is to determine whether the points being generated provide an accurate representation of the pulse being generated. An unselected check box generates a literal presentation of points. Default is True.

Open View Parameters

All of these parameters may be set from the open view or added as data inputs.

Frequency - The rate in Hertz at which pulses are generated.

Pulse Width - The width, in time, of the pulses. The time is measured from the mid-point of the low-to-high transition to the mid-point of the high-to-low transition. Pulse width must be a positive real number. Default is 5m seconds.

Pulse Delay - The time from the start of the waveform to the beginning of the first transition. Pulse Delay must be a positive real number. Default is 0.

Thresholds - Determine the thresholds used by Rise Time and Fall Time.
Low Threshold = (first percentage) * (high - low)
High Threshold = (second percentage) * (high - low)

0%-100%

10%-90%

20%-80%

Rise Time - The time, in seconds, to make the transition from the low threshold to the high threshold. Rise Time must be a positive real number.

Fall Time - The time, in seconds, to make the transition from the high threshold to the low threshold. Fall Time must be a positive real number.

High - The value of the waveform when the pulse is active. High must be a real number. Default is 1.

Low - The value of the waveform when the pulse is not active. Low must be a real number. If the value of Low is greater then the value of High the pulse generated is inverted. Default is 0.

Burst Mode - Enables or disables multiple pulses being generated at the Frequency. When Burst Rate is OFF, only one pulse is generated at the Frequency. When Burst Mode is On, a Burst Count number of pulses is generated at the Frequency. Default is OFF.

Burst Count - The number of pulses generated at the Rep Rate. Burst Count must be a positive integer. Default is 2.

Burst Rep Rate - The rate at which the Burst Count pulses are generated. Burst Rep Rate must be a real number greater than 1/pulse width.

Time Span: - The duration of the waveform (in seconds). Default is 20m seconds.

Num Points: - The number of points in the waveform. The time between points in the waveform is Time Span/numPoints. Num Points must be positive. Default is 256.

Location

Device [image] Virtual Source [image] Pulse Generator

See Also

Build Arb Waveform, Build Waveform, Comparator, Function Generator, and Noise Generator.


Clear Queue

Queue - Clear

Clears the given queue.

Location

System [image] Collections [image] Queue [image] Clear


Queue - Count

Counts the items in the queue.

Location

System [image] Collections [image] Queue [image] Count


Queue - Create

Creates a data structure called a queue.

Location

System [image] Collections [image] Queue [image] Create


Queue - Dequeue Item

Remove an item from the queue.

Location

System [image] Collections [image] Queue [image] Dequeue Item


Queue - Enqueue Item

Add an item to the queue.

Location

System [image] Collections [image] Queue [image] Enqueue Item


Queue - Enumerate

Provide a listing of items in the queue.

Location

System [image] Collections [image] Queue [image] Enumerate Items


Queue - Peek an Item

Peek at an item in the queue.

Location

System [image] Collections [image] Queue [image] Peek Item


Radio Buttons

See Selection Control.


Raise Error

Generates a user-defined error condition with associated error number (escape code) and text message. (This object was formerly called Escape.)

Use

Use Raise Error to stop execution of the current UserObject and generate an error that may be trapped by the error pin of an enclosing UserObject or the main work area. If the error is not trapped (by an error pin on a UserObject) and the escape code is non-zero, Raise Error stops the program and generates an error dialog box.

Raise Error may also be used in a UserFunction to generate an error trapped by an error pin on the object that called the UserFunction.

Open View Parameters

Code - An error number; it must be an Int32. VEE uses error numbers between 300 and 1,000; it is best to use error numbers exclusive of this range. Error codes between 950 and 999 are used for VEE Serious Error (VSE), so you cannot use error codes in that range, or a VEE Run Time Error will occur. You can enter the Code in the entry box or add it as a data input.

Message - The text message to output. You can enter the Message in the entry box or add it as a data input.

Notes

If VEE is invoked with the -r command line option, an entrapped error generated by Raise Error causes VEE to terminate. The Code and Message are written to stderr and 255 is returned to the operating system as the exit code.

To generate a specific exit code, use the Stop object.

Location

Flow [image] Raise Error

See Also

Error Output (Object Menu), Create UserObject, Exit UserObject, Exit Thread, Start, Stop, and Properties (Object)

To Trap an Error


Real32

An object that outputs a constant 4-byte real scalar or 1D Array.

Use

Use Real32 to set a real constant or to get user input. Click on the entry field to enter a value.

Example

To use Real32 as a prompt on a panel view, change the name of the Real32 object to a prompt such as Enter the offset:. The user fills in the requested information in the entry field.

Type in 100M*PI to have the Real32 Constant evaluate this formula and display the Real32 number answer.

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are scalar and Array 1D.

 ArraySize - When DataShape 1D Array is selected, ArraySize sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D Array is selected.

 ShowArrayIndices - When the property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is True.

Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When the property is True, the Initial Value is set at PreRun time. Default is False.

 InitializeAtActivate - When the property is True, the Initial Value is set at Activate time. Default is False.

Global Format - Use the default format. Default is True.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires a real value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Real32 is configured to be an array.

Location

Data [image] Constant [image] Real32

See Also

Alloc Real32, Complex, Constant, Coord, Date/Time, Selection Control, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real64, Text, Boolean, and Toggle Control.

To Use a Data Constant


Real64

An object that outputs a constant 8-byte real Scalar or 1D Array.

Use

Use Real64 to set a real constant or to get user input. Click on the entry field to enter a value.

Example

To use Real64 as a prompt on a panel view, change the name of the Real64 object to a prompt such as Enter the offset:. The user fills in the requested information in the entry field.

Type in 100M*PI to have the Real64 Constant evaluate this formula and display the Real64 number answer.

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are Scalar and Array 1D.

 ArraySize: - When DataShape 1D Array is selected, Size sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D Array is selected.

 ShowArrayIndices - When the property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is True.

Stepping Category: (disabled when DataShape is Array 1D)

EnableStepping - When the property is True, stepping controls appear at the right end of the entry field to let you scroll through values. Default is False.

DetentSize - When the EnableStepping property is True, this sets the size between values when using the stepping controls to scroll through values. Default is 1.

Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When the check box is selected, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When the check box is selected, the InitialValue is set at Activate time. Default is False.

NumberFormat: Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires a real value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the InitialValue field is always a scalar, even if Real64 is configured to be an array.

Location

Data [image] Constant [image] Real64

See Also

Alloc Real64, Complex, Constant, Coord, Date/Time, Selection Control, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real32, Text, Boolean, and Toggle Control.

To Use a Data Constant


Real64 Input

An object that displays a pop-up dialog box that accepts real number input.

Use

Use Real64 Input to prompt the user to enter a real number, accept the number, and check the number with a user-defined test for validity.

In the pop-up dialog box, when the OK button is pressed, the real number input by the user is output on the Value output pin. When the Cancel button is pressed, a 1 is output on the Cancel output pin.

Open View

  • Prompt/Label - The string that prompts the user to fill in the text field. You may add this parameter as a data input. Default is Enter Real Value:

  • Default Value - The text that is in the dialog's input field before anything is typed. If the user presses OK without typing anything, this text is output. You may add this parameter as a data input. Default is 5

  • Value Constraint - The equation that tests the input text for validity. You can use any mathematical expression or call a UserFunction. You may add this parameter as a data input. Default is 0<=value AND value<=10; which means it checks for user input of a value between 0 and 10. To accept any value, use the expression 1.

  • Error Message - The text that is output in a message box if the user input does not meet the Value Constraint. You may add this parameter as a data input. Default is You must enter a real number between 0 and 10.

Properties

  • PopupTimeoutEnabled - When this property is True, a Timeout output pin is added to the object. Default is False.

  • PopUpDuration - Sets the length of time the pop-up dialog box is displayed. After this period of time, the dialog box times out and a value of 1 is output on the Timeout output pin. No other outputs pins have data if the Timeout pin executes. This field is only available when the Timeout Enabled check box is selected. Default is 60 seconds.

  • PopupOKLabel - Sets the button label to OK if True. You may also use alternative wording if your users are not native English speakers. Regardless of the wording, the button's function remains the same.

  • PopupCancelLabel - Sets the button label to Cancel if True. You may also use alternative wording if your users are not native English speakers. Regardless of the wording, the button's function remains the same.

  • PopupPasswordMasking - When this property is True, the input text is echoed as asterisks (*). This feature is useful when the operator is entering sensitive data such as a password. The string that is output on the Value output pin is not masked. Default is False.

Notes

The default location of the pop-up dialog box is approximately at the center of the work area. If you move it, next time it will pop-up to the new location.

The title text of the error message dialog box is the same as the Real64 Input object title.

To respond to the pop-up dialog box using only the keyboard: when the dialog box pops up, start typing and use Enter and Esc keys. Use the Tab key to move between the input field and the buttons and then select the buttons with the Space bar.

The pop-up dialog box and the error dialog box are only displayed while the program is running. While the pop-up dialog box is displayed, the entire program pauses execution, then continues when the dialog box is closed.

Location

Data [image] Dialog Box [image] Real64 Input

See Also

File Name Selection, Int32 Input, List Box, Message Box, Text Input, UserObject and Object Menu

To Use a Data Input Dialog Box


Real64 Knob

An object that outputs the Real64 value of the knob.

Use

Use Real64 Knob to input values. Real64 Knob is particularly useful on a panel.

Open View Parameters

The open view displays fields for the knob's current value, minimum, and maximum values, and the knob control.

Properties

Orientation - Sets the orientation of how the Knob is displayed.

 ShowDigitalDisplay - If the property is True, the current value of the knob is displayed in an edit field at the bottom of the open view of the object. When you modify this value, the position of the knob changes. Default is True.

ShowTics - Controls visibility of scale’s tic marks and labels. Default is True.

 Logarithmic - When property is True, changes scale from linear to logarithmic. Default is False. When turned on, Detents changes to Steps/Decade.

 LabelSpacing: - Controls which tic marks are labeled with the scale values. Default is Every Other Tic.

 Detents or Steps/Decade: - On a linear scale, Detents sets the distance between the values that are available from the Knob. On a log scale, Steps/Decade sets the number of steps available within each decade from the Knob. If other values are entered, they are rounded to the nearest detent. Default for Detents (linear scale) is 1m. Default for Steps/Decade (logarithmic scale) is 1.0.

Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When the property is True, the Initial Value is set at PreRun time. Default is False.

 InitializeAtActivate - When the property is True, the Initial Value is set at Activate time. Default is False.

NumberFormat Category:

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, Disable Editing, MaxValue, MinValue, and Detents:

The Default Value input allows you to programmatically change the current value. This input requires a real scalar value.

The Reset input allows you to programmatically set the value to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the current, minimum, and maximum values can be changed in the open view.

The MaxValue and MinValue inputs allow you to programmatically set the min and max value fields. These inputs require a real scalar value.

The Detents input allows you to programmatically set the detent value.

Location

Data [image] Continuous [image] Real64 Knob

See Also

Complex, Selection Control, Int32, Int32 Slider, Int32 Knob, PComplex, Real64, Real64 Slider, Text, Toggle Control, and Object Menu

To Use a Data Slider and Knob


Real64 Slider

An object that outputs the Real64 value of the slider.

Use

Use Real64 Slider to input values. Real64 Slider is particularly useful on a panel.

Open View Parameters

The open view displays a field for min, max, slider value, and slider control.

Properties

Orientation - Sets the orientation of how the Slider is displayed.

 ShowDigitalDisplay - If the property is True, the current value of the slider is displayed in an edit field at the top of the open view of the object. When you modify this value, the position of the slider control changes. Default is True.

ShowTics - Controls visibility of scale’s tic marks and labels. Default is True.

 Logarithmic - When this property is True, changes scale from linear to logarithmic. Default is False. When turned on, Detents changes to Steps/Decade.

 LabelSpacing: - Controls which tic marks are labeled with the scale values. Default is Every Other Tic.

 Detents or Steps/Decade: - On a linear scale, Detents sets the distance between the values that are available from the Slider. On a log scale, Steps/Decade sets the number of steps available within each decade from the Slider. If other values are entered, they are rounded to the nearest detent. Default for Detents (linear scale) is 1m. Default for Steps/Decade (logarithmic scale) is 1.0..

Wait for Input - When the property is True, the object does not operate until the object's value is changed. When the property is False, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When the property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When the check box is selected, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When the check box is selected, the InitialValue is set at Activate time. Default is False.

NumberFormat:

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, Disable Editing, MaxValue, MinValue, and Detents:

The Default Value input allows you to programmatically change the current value. This input requires a real scalar value.

The Reset input allows you to programmatically set the value to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the current, minimum, and maximum values can be changed in the open view.

The MaxValue and MinValue inputs allow you to programmatically set the min and max value fields. These inputs require a real scalar value.

The Detents input allows you to programmatically set the detent value.

Location

Data [image] Continuous [image] Real64 Slider

See Also

Complex, Selection Control, Int32, Int32 Knob, Int32 Slider, PComplex, Real64, Real64 Knob, Text, Toggle Control, and Object Menu

To Use a Data Slider and Knob


Record Constant

An object that outputs a constant of the Record data type, of shape scalar or 1D Array.

Use

Use the Record Constant object to define and build a Record constant, or to interactively edit an existing record or array of records.

Open View Parameters

In the open view there is a Field name button and a Value button (or type-in field) for every field in the record. (By default, the Field name buttons A and B correspond to the Value fields "Text field" and "1.25", respectively.) If the record DataShape is Array 1D, there is an additional field in the open view for the index into the array (0, 1, etc.) To step through the array values, First, Prev, Next, and Last buttons are provided.

Field name -- A button that, when pressed, pops up a dialog box that allows the user to re-name the record field, and change its type and shape. An error will occur if you attempt to rename a field to an existing field name. Field names are not case sensitive (lowercase and uppercase letters are equivalent). When changing the data type, VEE will attempt to coerce the existing data into the new data type, subject to the rules about data type coercion.

Value -- Allows you to edit the values in the field. If the field is a scalar container of a data type other than Enum, Value is a type-in field. That is, you can click on the field and type in the desired value. If the field is an Enum or Array 1D container, the Value field is a button, which brings up a dialog box to allow you to select the values. If the field is an array of two or more dimensions, the values may not be edited.

Object Menu

Add Record -- Adds a record at the end of the record array. The new record is a copy of the last record in the array. (This menu selection is not active for record scalars.)

Insert Record -- Inserts a record at the position in the record array that you are currently viewing. The new record is a copy of the record that you were viewing. (This menu selection is not active for record scalars.)

Delete Record -- Deletes the record that you are currently viewing from the array. (This menu selection is not active for record scalars. Also, for record arrays, the selection is active only if there is more than one record in the array.)

Add Field -- Adds a new field to the record at the end of the field list. A dialog box will allow you to define the name, type, and shape of the new field.

Insert Field -- Inserts a new field to the record at a specified position. A dialog box allows you to define the name, type, and dimension of the new field. A second dialog box allows you to specify the insertion point.

Delete Field -- Allows you to delete record fields. A dialog box will list the available fields to delete. This selection is available only if the record has more than one field.

Generate

Declared Variable -- Allows you to generate a declared variable object which matches this Record configuration. Both the Record constant and the declared variable have the same number of fields and each field has the same name.

Unbuild Record -- Allows you to generate an Unbuild Record object whose outputs match the Record configuration.

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are scalar and Array 1D.

 ArraySize: - When DataShape 1D Array is selected, Size sets the length of the array.

 ArraySizeFixed - When the property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D Array is selected.

 Schema Fixed - When the property is True, the format ("schema") of the record is fixed, and may not be modified. This is useful when allowing users to modify Record values interactively on a pop-up panel.

NumberFormats:

Global Format - Use the default format. Default is on.

Integer: - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires a Record value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. (Numeric fields become zero and Text fields become null strings.) The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

The Default Value pin is useful for editing large record arrays (for example, a record array "pulled in" with the From DataSet object). Just send the record array into the Default Value pin to set the initial value for the Record Constant. You can then view and interactively edit the entire record. The data values may be changed, and also the type, shape, and mappings of the fields may be changed (unless the field is itself a record). Once you have edited the record, it can be output to a new dataset or file (using To DataSet or To File). The Record Constant object does not allow you to edit a field that is itself a record -- it will only allow you to view the field and its data.

Note that the Record Constant object does not allow you to create a record of records. That is, the Record Constant does not allow you to add a field that is a record. However, all other VEE record devices (such as Build Record and Set Field) do allow this. Recursion is allowed up to the limit of available user memory. That is, a record may have a field that is a record, which has a record field within it, and so forth. The shape of a record container may only be either a scalar or a one-dimensional array.

Location

Data [image] Constant [image] Record

See Also

Build Record, From DataSet, Merge Record, Set Field, To DataSet, buildRecord() and UnBuild Record.

To Create a Record Constant


Remove

Removes a sub-string you specify from a given string.

Location

System [image] String [image] Remove


Repeat

A menu item.

Use

Use Repeat to access the following iterators and iteration-control objects:

For Count

For Range

For Log Range

Until Break

On Cycle

Next

Break

Notes

You can nest iterators.

Execution of the subthread hosted by the iterator continues until one of the following occurs:

All objects that can, have operated. The subthread iterations have been completed.

A Break object operated. The subthread is deactivated and the sequence output pin is activated.

A Next object operated. The subthread is deactivated and the iteration counter is incremented.

When the iteration subthread has completed, the sequence output pin is activated.

Location

Flow [image] Repeat

See Also

Break, For Count, For Range, For Log Range, Next, On Cycle, and Until Break.

To Loop Part of a VEE Program


Replace

Replaces this object and its connections with another object.

Use

Use Replace to replace an object while retaining the connections.

Replace puts a copy of the object that is replaced in the Paste buffer.

Notes

Each Replace overwrites the previous content of the Paste buffer with the original object.

Pins are connected from top to bottom. If there were more lines connected to the original object than there are pins on the new object, the extra lines are deleted. If there were fewer lines connected to the original object than pins on the new object, the bottommost pins on the new object are left unconnected.

Replace works only within a single context. For example, to Replace an object in a UserObject, first place the replacement object in the UserObject context.

Replace is not available unless an object is connected to one or more objects.

Location

On each object menu [image] Replace

See Also

Object Menu, Cut (Object Menu), Copy, and Paste.


Replace (System Menu)

Replace

Replaces a sub-string in a given string with text you provide.

Location

System [image] String [image] Replace


Restore (Object Menu)

Restores the object to its open view.

Use

Use Restore to show the open view of an object.

Notes

Restore is available from the icon view of all objects.

From a maximized UserObject, Restore will resize the open view to its non-maximized size.

Short Cuts

To restore an object, double-click on the icon.

Location

On the object menu [image] Restore

See Also

Minimize (Object Menu).


Run/Resume

Causes all suspended threads to continue running after the program has been paused.

Use

Use Run/Resume to resume program execution after the program has been paused. The program pauses if the Pause button is pressed, if a breakpoint is reached, or if a Step function is used.

Run/Resume is primarily used to continue execution between breakpoints and is usually used in conjunction with the other debugging tools.

Notes

The Run/Resume button on the toolbar is the same as the Run button. Run/Resume is not available if Stop has been pressed.

Short Cuts

Pressing the CTRL + G keys or the F5 function key will activate Run/Resume.

Location

Debug [image] Run/Resume

See Also

Pause, Run, Start, Step Into, Step Over, Step Out, Stop, and Toggle Breakpoint.

To Step through a Program


Reset Tool Bar/Window Layout

Reset Toolbar / Tool Window Layout

The command resets the toolbar and tool window to the VEE default factory layout. When you run this command, the following actions occur:

  • All toolbars and windows are moved to their default positions.

  • Toolbars and windows that are closed in the default IDE layout are closed by the command.

  • Toolbars and windows that are open in the default IDE layout are opened by the command.

See Also

To Arrange and Dock Tool Windows, Save and Load Tool Bar / Window Layout.


-Run

Starts the execution of all threads in a program.

Use

Use Run to begin the program execution. If Start objects are used on threads in the main work area, execution begins with those objects.

When you select Run, VEE PreRuns all threads to clear data and check for feedback. If Execution Mode in Default Preferences is set to VEE 4 or higher, VEE predicts the order of execution of objects, determines what data types are flowing on certain lines, and generates a compiled code for each object.

Notes

If you have several threads in your program and want to run only one of them, connect a Start object to that thread. Press the Start object on the thread you want to run.

Short Cuts

Press CTRL+G or F5 to run the program.

Location

Debug [image] Run

See Also

Pause, Run/Resume, Start, Step Into, Step Over, Step Out, and Stop.

To Start a VEE Program


Sample & Hold

An object that stores the most recently received data container. Activating the XEQ pin outputs the stored container.

Use

Use Sample & Hold to capture the last data present on the input pin when XEQ is activated.

Example

Use Sample & Hold to preserve data generated by objects in subsequent thread segments of either If/Then/Else or Conditional flow objects that are also in an iteration sub-thread.

Notes

The Sample & Hold is generally not needed unless both iteration and flow branching are present in a thread. Objects will normally retain the most recently received data container on their input pin(s) by default.

Only the most recent data container arriving at the InData input will be saved by the Sample & Hold. As new data arrives, it over-writes the existing data.

If the Sequence In pin is connected, both the InData input and the Sequence In pin must be activated before a data container will be accepted to replace the existing stored data.

The Sample & Hold operates when the XEQ pin is activated. Propagation will proceed as far as possible before the Sequence Out pin is activated.

The contents of the Sample & Hold are cleared by PreRun and Activate. If XEQ is activated with no stored data, an error will be generated.

Because XEQ is required on the Sample & Hold, you cannot delete it or add another XEQ pin.

Multiple XEQ activations each re-send the most recent stored data if no new data has arrived.

Location

Flow [image] Sample & Hold

See Also

Repeat, If/Then/Else, Conditional, UserObject, Properties (Object), and Object Menu


Save

Copies the program in the work area to a previously specified filename.

Use

Use Save periodically to write your program to a file.

Caution

A file saved in Agilent VEE Pro 8.0 or higher format cannot be retrieved into earlier versions of VEE.

Notes

Save writes your program to the file name specified in Save As or Open. If a program was created from a New work area and no Save As was done, Save prompts you for a file name. As the program is being written, the pointer changes to a pencil.

VEE allows you to save colors and fonts (as defined by Default Preferences) in your program file. A Save colors and fonts with program check box has been added to the Save File Dialog Box.

VEE allows you to embed I/O configuration information in the program itself. To enable embedding of the configuration information, a Save I/O configuration with program check box has been added to the Save File Dialog Box. See Instrument Manager for more information on saving an I/O configuration.

Save does not ask for confirmation when overwriting a file.

Saving a file may affect its compatibility. For example, a version 5 file that is retrieved into version 6 and saved is no longer compatible with version 5.

Short Cuts

Press CTRL+S to save a program.

Location

File [image] Save

See Also

Merge, Open, Save As, and Save Objects.


Save As

Copies the program in the work area to a specific file.

Use

Use Save As to specify a file name for your program and write the program to that file.

Select Save colors and fonts with program to save all the default colors and fonts in the program file that are selected in the Default Preferences dialog box. This ensures that whoever opens your program will also get all of your default colors and fonts. If this option is not selected, only the colors and fonts explicitly set in your program are saved in your program file. This allows others using your program to retain their own default colors and fonts. If an existing program is loaded, the option is set according to how the program was saved previously.

Save As enables Save I/O configuration with program by default. You can un-check this selection if you do not want the embedded I/O configuration. VEE allows you to embed I/O configuration information in the program itself. See Instrument Manager for more information on saving an I/O configuration.

Caution

A file saved in Agilent VEE Pro 8.0 and higher format cannot be retrieved into earlier versions of VEE.

Notes

If you attempt to overwrite an existing file, you are asked to confirm that action. As the program is being written, the pointer changes to a pencil.

The file name specified in Save As becomes the name used in subsequent Save operations.

The current file is saved as filename.bak; the new saved version is just filename. Note that if the filename already includes an extension (such as .vee) that extension is replaced with .bak.

VEE allows you to embed I/O configuration information in the program itself, rather than using the veeio resource file. To enable embedding of the configuration information, a Save I/O configuration with program check box has been added to the Save File Dialog Box. See Instrument Manager for more information on saving an I/O configuration.

Saving a file may affect its compatibility. For example, a version 5 file that is retrieved into version 6 and saved is no longer compatible with version 5.

Short Cuts

Press CTRL+W to Save As.

Location

File [image] Save As

See Also

Default Preferences, Merge, Open, Save, and Save Objects.


Save Documentation

Creates a text file containing a description of the current program.

Use

Use Save Documentation to get a listing of your program for documentation purposes. The output file from Save Documentation includes the following information:

Source file name.

Documentation date.

Current version number of VEE.

Save file version.

System preferences (except colors and fonts).

Object names and types.

Open view information on objects (such as a Constant value or transactions).

Object description text entered from Description.

Notes

Save Documentation replaces the veedoc utility which existed in prior revisions of VEE.

Do, Junction, and Gate objects are not included in the Save Documentation file unless they have description text entered from Description.

The numbers assigned to each object in the Save Documentation file correspond to the numbers printed next to the object when Print All is used.

Because constant data is printed on a single line, arrays and records are not printed so that the file can be read by commonly-used word processors.

Save Documentation does not save color and font information or I/O configuration.

Location

File [image] Save Documentation

See Also

Default Preferences, Print Program, Save, and Save As.

To Document Your Program


Save Objects

Copies the selected objects to a specific file.

Use

Use Save Objects to specify a file name for a set of objects and write the objects to that file. Save Objects is generally used to save a group of objects into a library of common functions that is included in other programs.

Notes

Use Save Objects to copy a set of objects from your program that you use in other programs. Save Objects allows you to build up a library of your own functions. As the objects are being written, the pointer changes to a pencil.

If you attempt to overwrite an existing file, you are asked to confirm that action.

Save Objects does not save color and font information or I/O configuration.

Location

File [image] Save Objects

See Also

Merge, Open, Save, and Select All.

To Create a Library of UserObjects

To Secure a UserObject


Send to Back (Object Menu)

Send to Back

Send an Object to the back of the viewable plane.

Use

An object menu choice on Panel, Send to Back places an object in the background of the viewable plane, changing the z-order of the object.

See Also

Bring to Front (Object Menu)


Select All

Selects all objects in the front window to be acted on.

Use

Before you use the object features in the Edit menu, you must select an object or a set of objects to be acted on. Choosing Select All will select all of the objects in the front or active window. When an object is selected, it has a shadow highlight. To select more than one object, but not all objects, press and hold CTRL while selecting the objects with the left mouse button. After the objects are selected, choose an editing function such as Cut or Copy.

Notes

Any objects previously selected are deselected when Select All is used.

If you select objects by mistake, deselect all objects by clicking on the work area. Or press the CTRL key while clicking on the unwanted objects to deselect them.

Only objects in the same VEE context (UserObject, UserFunction, etc) can be selected together.

Short Cuts

Press CTRL key while clicking the left mouse button on objects. Or press the CTRL key while dragging (with the left mouse button down) to rubberband select objects.

These shortcuts allow you to toggle the selection of objects. These methods do not deselect all previously selected objects before selecting other objects (as Select All does).

Pressing CTRL + A will select all objects in the active detail view/panel view.

Clicking the left button on an object selects it, however it also deselects any objects already selected.

Location

Edit [image] Select All

See Also

Add To Panel, Align, Copy, Create UserObject, Create UserFunction, Cut, Print Objects, Replace, Paste, and Save Objects.


Selection Control

Object that outputs an enumerated value from a user-defined list. Selection Control objects have a variety of display formats, but they all work the same way.

Use

Use Selection Control objects to set an enumerated constant or to get user input that is chosen from a list of acceptable choices. The first item in the list is assigned ordinal position 0; the nth item in the list is assigned ordinal position n-1.

Object Menu

Edit Enum Values - Allows you to add valid selections to the enumerated list of choices or edit existing choices. Add a choice, and then press the Tab key to move to the next entry in the list. You can move back up in the list by pressing Shift+Tab.

Properties

Format property: - Specifies the appearance of the Selection Control object and the method of selecting a choice. The default format is whichever object you chose from the menu.

Radio Buttons - The choices are all displayed. The selection is made when the radio button next to the choice is pressed.

Cyclic Button - The choices cycle as the button field is clicked on. This choice is best used if there are two choices such as On/Off or Stop/Go or in a dialog box where the choice is confirmed by another button.

List - The choices are presented in a list box with scroll bar if all choices can't be shown at once The selection is made when the choice is clicked on.

Drop-Down List - The choices are presented in a list box that drops down when the arrow to the right of the field is pressed. The selection is made when the choice is clicked on.

Pop-Up List - The enumerated choices are presented in a list box in a dialog box that is displayed when the button field is pressed. The selection is made when the choice is clicked on and OK is pressed.

Slider List - The enumerated choices are presented as tic labels on a slider. The selection is made when the slider button or the label is clicked on.

Execution group:

Wait for Input - When the check box is selected, the object does not operate until the object's value is changed. When the check box is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is off.

Auto Execute - When the check box is selected, the object operates and starts the rest of the program when a value is selected. If the program is already running, Auto Execute is ignored. Default is off.

FormatSliderLayout property:

Horizontal | Vertical - Sets the orientation of how the slider is displayed. These are only valid when Format is set to slider list.

Initialization category:

Initial Value - Specifies the value to be set. Default value is the first selection from the list.

Initialize At PreRun - When the check box is selected, the Initial Value is set at PreRun time. Default is off.

Initialize At Activate - When the check box is selected, the Initial Value is set at Activate time. Default is off.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting an initial value is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, Disable Editing, and Enum Values:

The Default Value input allows you to programmatically change the current value. This input requires a Text Scalar value (or any data that can be converted to a Text Scalar, including an Enum). This value must match one of the possible Enum values (case sensitive).

The Reset input allows you to programmatically set the current value to the first (0 ordinal) value in the list. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the values can be changed in the object’s open view.

The Enum Values input allows you to programmatically set the list of possible values for the Selection Control. This input requires Enum, a Text Array 1D, or any data that can be converted to a Text Array.

Enum containers are automatically converted into Text for many objects, including Collector, Concatenator, Sliding Collector, and most Formula objects.

To get the selected value’s ordinal value, connect a line to the Ordinal output rather than the selected string, or use ordinal().

Example

To use a Selection Control as a prompt on a user panel, change the name of the object to a prompt such as "Choose the type of test:".

Location

Data [image] Selection Control

See Also

Complex, Constant, Coord, Date/Time, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real32, Real64, Text, Toggle Control, Boolean, and List Box.

ordinal(x).

To Use a Data-Selection Object


Send Mail

This powerful object allows the sending of mail. You need an SMTP server address as a pre-requisite. The rest of the requirements are standard email features; to, from, subject, and message.

Location

System [image] Send Mail


Service Manager

The Service Manager is a prerequisite for the use of Remote Functions. It manages communications between the "service" that runs on the remote host computer and the "client" that runs on the local host computer. You must start it on the remote host system prior to initiating the use of remote functions.

When running Service Manager on a system with Microsoft XP SP2, the new firewall feature of that OS may cause an issue. It's possible the Service Manager may be blocked the first time it is run. If so, you will receive a Security Alert. Choose Unblock this program, despite the security risk. and click OK.

See Also

Remote Functions


Set Field

An object that allows you to modify a field of an existing record.

Set Field is obsolete and cannot be added to new programs, though it is still supported on older programs that already contain the object. Use the Assignment Formula object as a substitute. It is located on the Function & Object Browser under Operators => Assignment.

Use

Set Field as used to modify the value of a field of an existing record. The Set Field object is actually a Formula object that assigns the value specified by the right-hand expression to the field specified by the left-hand expression. The value in the right hand expression can evaluate to a scalar, an array, another record, or a field in a record.

Set Field is a short-cut for un-building a record, changing one field, and re-building the data into a record. Note that there are two output terminals, Result and Rec. Result outputs only the field referenced in the object. Rec outputs the entire record. Also, the left and right-hand expression results must match in type and shape. You cannot use Set Field to change the "schema" (type and shape) of the input record.

Open View Parameters

Expression input field -- This input field allows you to change an element of a record directly. The left-hand expression allows a subset of Formula mathematical syntax, which allows you to specify a field of a record. The A.B dot syntax, as well as a subset of the A[2] sub-array syntax, is supported to specify a particular field of the record to be changed. See "Notes" below for further details of the allowed syntax. The right-hand expression allows any mathematical expression that is allowed in a Formula object. This expression has access to all input containers, variables, and functions. The right-hand expression is evaluated and the resulting value is stored in the field of the record specified by the left-hand expression.

Notes

The name of the record output pin must match the name of the input record to be modified, and the left-hand expression must begin with that name. For example, if the record pins are named Rec, the left-hand expression must be something like Rec.A or Rec[1]. The left-hand expression must be a single expression that specifies which field of the input container is to be modified.

There may be confusion over the names of inputs, outputs, and record fields. For example, if the name of the record input pin and the record output pin is Rec (they must match), the expression Rec.A specifies the A field in the input record. On the other hand, the expression A*2 refers to the A data input of the Set Field object. Thus, Rec.B=A*2 sets the B field of the output record equal to twice the value of the A data input. On the other hand, Rec.B=Rec.A sets the B field of the output record equal to the value of the A field of the input record.

The complete input record container is output on the record output pin, but the specified field is modified. For example, suppose the input Rec is a record with two fields x and y, where x is a Text scalar with value "hello" and y is a Real64 scalar with the value 1.2. If the left-hand expression specifies Rec.y, and the right-hand expression evaluates to 5.6, the Rec output container will be a record with two fields x and y, where x is a Text scalar with value "hello" and y is a Real64 scalar with the value 5.6. The Result output will contain only the y field, in this case a Real64 scalar with a value of 5.6.

The field specified by the left-hand expression and the result of the right-hand expression must match in type and shape ("schema"). That is, the operation of the Set Field object cannot change the schema of the input record -- only the data in the specified field can be changed. For example, suppose input Rec is a record with two fields x (a Text scalar) and y (a Real64 scalar). If the left-hand expression specifies Rec.y, the right-hand expression must result in either a Real64 scalar, or something that can promote to a Real64 scalar. Otherwise, an error will result.

Record arrays require special attention. A record array is an array consisting of individual record elements, each consisting of fields. You can use Set Field to change one field of one element in a record array. For example, if you create a record 1D array and you want to change the f field of the third record element of the array, specify Rec[2].f (for a zero-based array) in the left-hand expression. In this case, the result of the right-hand expression is placed in the f field of the third element of the record 1D array. None of the other fields of Rec[2] are changed, nor are any fields of the other record elements of the array (for example, Rec[0].f and Rec[1].f).

On the other hand, you can use Set Field to modify a particular field in every record element of a record array. For example, suppose you specify Rec.f in the left-hand expression where Rec is a record 1D array with n elements. In this case, the result of the right-hand expression is copied into every Rec[x].f field, where x is from 0 through n-1. In other words, the f field is changed in every record element of the array.

The left-hand expression must be a single expression specifying which part of the input record is to be modified. For example, Rec+2 and sine(Rec) are not valid as left-hand expressions. Also variables are not allowed in the left-hand expression.

The syntax allowed for the left-hand expression is limited:

The A.B dot sub-record syntax may be used any number of times for record of record containers (there is no limit on recursion). Suppose that record A has a field b, which is itself a record. The record field b has a field c, which is a record containing field d. To specify that lowest level field d, you can use A.b.c.d as the left-hand expression.

The A[x] sub-array syntax is more limited, and may be used only once, before the last dot. For example, A.b.c[1].d is valid as a left-hand expression, but A[2].b.c.d and A[2].b[2].c are not allowed. Also, A[1] and A.b.c[1:2] are not allowed. However, the A[x] sub-array syntax, supported before the last dot, does support the "colon and asterisk" syntax. For example A[1:2].b and a.b.c[2:*].d are valid left-hand expressions.

Note the difference between A[1].b and A.b[1]. The first is a record 1D with a field b. The second is a scalar record containing a field b, which is a 1D array.

Location

Data [image] Access Record [image] Set Field

Set Field is obsolete. This menu item gets the Assignment Formula object.

See Also

Assignment, Build Record, Formula, Get Field, Record Constant, SubRecord, and UnBuild Record.

Using Assignment Operations

To Change a Field in a Record


Set File Creation Time

Sets the file creation time for the given file.

Location

System [image] File [image] Set File Creation Time


Set Last File Access Time

Sets the last file access time for the given file.

Location

System [image] File [image] Set Last File Access Time


Set Mappings

An object that assigns mapping to an array.

Use

Use Set Mappings to map one or more dimensions of an array linearly or logarithmically over a range of real values.

Open View Parameters

Num Dimensions - The number of dimensions in the input array. Num Dimensions must be an integer. Minimum is 1. Maximum is 10. Default is 1. Changing the value of Num Dimensions changes the number of rows available to set the parameters for Mapping, From, and To - one row per dimension.

Mapping - Linear or Log for each dimension. Default is Linear.

From - The lower limit of the mapping range (inclusive) for each dimension.

To - The upper limit of the mapping range (inclusive) for each dimension.

From and To may be added as data inputs.

Notes

If a Waveform or Spectrum is input, its elements are remapped to your specifications. Log mapping is not allowed on a Waveform.

There are the same number of points as sampling intervals. Each point is at the beginning of the sampling interval.

Set Mappings does not allow an array of Coord as input because the Coord array is already explicitly mapped.

The mappings on arrays are used in the XY displays for Autoscale and various math functions.

The From and To values must be different.

The value of the Num Dimensions field must match the number of dimensions of the input array.

Location

Data [image] Access Array [image] Set Mappings

See Also

Allocate Array, Collector, Get Mappings, Line Probe, Sliding Collector, and Properties (Object)


Set Values

A Formula object that allows you to change an element of an array container.

Use

Use Set Values to modify elements of an array of any type and size. This object is a Formula object pre-charged with an expression that can change an array element.

You can connect several containers to the inputs on the Set Values object: the array to be changed, the scalar data to be added, and the indices specifying the array location to put the scalar data.

Input new values for the array and the index of the element you wish to replace. When all changes are done, the object outputs the modified array as well as the individual element that was changed.

Open View Parameters

Expression input field - This input field allows you to change an element of an array directly. The left-hand side of the expression allows a subset of Formula mathematical syntax, which allows you to specify the element of the array that you wish to change. The A[2] sub-array syntax is supported to specify a particular array element to be changed.

Notes

All arrays are zero-based; all indices for arrays are zero based.

To initially create an array use the Allocate Array [image] objects.

The value to be inserted in the array must be of the same type as that of the array, or promotable to the same type.

Location

Data [image] Access Array [image] Set Values

See Also

Allocate Array, Build Data, Collector, Formula , Get Values, ramp (numElem, from,thru), Set Mappings, and Sliding Collector.

Using Assignment Operations


Set Variable

An object that sets the data value of a variable.

Use

Use the Set Variable object to set the data container (type, shape, and values) of a variable (by name). This variable can then be used by name in other parts of the VEE program.

Undeclared Global Variables created (with Set Variable) in one context of a program can be used as data in another context of that program. For example, a Set Variable in the root context of a program could create an undeclared global variable, which could then be used as data by including a Get Variable in a UserObject. This is especially useful when the program contains several nested layers of UserObjects.

Variables that are set with Set Variable may also be used by name in the expression fields of the following devices: Formula, If/Then/Else, Get Values, Get Field, Set Field, From DataSet and all devices using expressions in transactions, including To File, From File, Direct I/O, From Stdin, To/From Named Pipes, and Sequencer.

Open View Parameters

The open view displays a field for the name of the variable. The name is not case sensitive (either lower-case or upper-case letters may be used). Thus globalA is the same variable as GLOBALa. The name field may be added as a control input.

Notes

To avoid unexpected results, your program must ensure that a variable is set with Set Variable before a Get Variable object (or an object that includes the variable name in an expression) executes. Generally, the best way to ensure this is to connect the sequence output pin of the Set Variable object to the sequence input pin of the Get Variable object, or other object that uses the variable. However, there are cases when the sequence input pin need not be connected. For further information about this, refer to Tell Me About... Variables in the Contents and Index under the Help menu of VEE.

If Delete Variables at PreRun is on (the default), all variables are deleted before your program executes. If Delete Variables at PreRun is turned off, variables will not be deleted, and you must program carefully to avoid propagating invalid data.

Global variables are truly global since they are not defined at a UserObject level. A global variable that is defined in one context of a program can be used in any other context within the program. For example, you can define a global variable with a Set Variable object in the root context of the program, and then include a Get Variable to get that global variable in a UserObject or UserFunction. However, you will need to avoid name conflicts throughout the program:

If two or more Set Variable objects attempt to set the same variable (with the same name), the current value will be overwritten as each Set Variable executes. This may result in unexpected behavior if you are unaware of the duplicate names.

If there is a data terminal variable with the same name as a variable, the data terminal variable will take precedence.

For further information, refer to Tell Me About... Variables in the Contents and Index under the Help menu of VEE.

Set Variable cannot set part of a variable that is an array or record. If you want to manipulate an array using globAry[2] = 3 or a record using globRec.field = 2, then use the Assignment Formula to enter these expressions.

The differences between Assignment in a Formula and Set Variable are subtle. Set Variable can create undeclared variables, initialize declared variables, and modify all variables. An Assignment Formula cannot create undeclared globals. Also, Set Variable cannot modify part of a variable as can an Assignment such as globalAry[1] = 2.

It is better to use an Assignment Formula when setting variables for ActiveX objects. If the global variable g_cells is declared and initialized as a cell of a Microsoft Excel worksheet, the Assignment g_cells = 2 in a Formula actually performs the default property set on g_cells. This has the same effect as g_cells.item = 2, which places the value 2 into that cell in Excel. This method maintains g_cells as a pointer to that cell. If you use Set Variable, the global would actually be overwritten so that g_cells would be an integer, not a pointer to a cell in Excel.

Location

Data [image] Variable [image] Set Variable

See Also

Assignment, Default Preferences, Delete Variable, Get Variable, and Properties (Object)

Using Assignment Operations

To Create a Variable


Shift Register

An object that outputs the previous values of the inputs.

Use

Use Shift Register to access the previous values of the input.

Notes

Add outputs to Shift Register to access previous values.

The Shift Register starts with all its outputs set to nil. Each time the object is activated, the data from the input is copied to the "current" output terminal. Data that was in the current output is moved to the 1 Prev output. The data from previous executions is shifted down the output terminals to the last output terminal.

Additional outputs may be added so the user may access the data from the "n" previous executions of a thread or program. Turn Clear at PreRun and Clear at Activate off from the Properties window to retain data over successive program executions.

Location

Device [image] Shift Register

See Also

Logging AlphaNumeric, Sliding Collector, and Properties (Object)


Show Config (Object Menu)

Displays a dialog box that shows the I/O configuration of an instrument driver panel, component driver, or a direct I/O object.

Use

From the object menu of an instrument driver panel, component driver, or a direct I/O object, select Show Config to view the configuration specified with I/O [image] Instrument Manager.

To change any configuration parameter use I/O [image] Instrument Manager. Note that any change will affect all other objects using that instrument with Direct I/O. To change the device in a Direct I/O object, edit the name field to choose a new device. Note that the transactions in the Direct I/O object may not be compatible with the new device.

Location

On an instrument driver panel, component driver, or a direct I/O object:

From the object menu [image] Show Config

See Also

Instrument Manager.


Show Data Flow

Shows the route that data takes through the program.

Use

Use Show Data Flow as a debugging tool to show the flow of data between input and output pins. A small square marker is used to trace the flow of data propagation along the lines. Even nil data is shown this way.

When Show Data Flow is set, the menu selection has a checkmark on its left.

Notes

Show Data Flow is often used with Show Execution Flow. These debugging tools will slow the execution of your program.

You can change the rate at which the marker moves by selecting File [image] Default Preferences. In the Default Preferences dialog box, in the Debug group, set the Data Flow Rate.

Location

Debug [image] Show Data Flow

See Also

Line Probe, Default Preferences, Profiler, Show Execution Flow, Step Into, Step Over, Step Out, and Toggle Breakpoint.

To View Data Flow and Program Execution


Show Execution Flow

Highlights the object that is currently executing.

Use

Use Show Execution Flow as a debugging tool to show the currently operating object. A highlighted color border (the default is light green) appears around the object and remains until the operation is complete. The currently executing transaction will also be highlighted in objects that include a list of transactions, such as Direct I/O, Sequencer, To File, From File, etc.

When Show Execution Flow is on, the menu selection has a checkmark on its left.

Notes

Show Execution Flow is often used with Show Data Flow. These debugging tools will slow the execution of your program.

Show Execution Flow also highlights objects that have already executed. To see which objects have executed after a pause or an error in the currently open window, click on Show Execution Flow.

Location

Debug [image] Show Execution Flow

See Also

Line Probe, Profiler, Show Data Flow, Step Into, Step Over, Step Out, and Toggle Breakpoint.

To View Data Flow and Program Execution


Size (Object Menu)

Changes size of an object or multiple objects.

Use

Use Size to change the size of an icon, open view, or window. After you select Size, the pointer changes shape to an arrow. Click and drag the arrow to the new size of the object; an outline rectangle shows you the size of the object. Another way to resize is to position the arrow pointer to where you want the lower right corner of the object and click. In both Panel and Detail view, you can select a group of objects using the CTRL key and the left mouse button. After selection, place your cursor over the edge of one of the objects until you get the double-headed arrow. Drag the cursor to size your objects.

Notes

In Detail view, Size retains the connections with other objects. If Automatic Line Drawing is set, it may take a few moments to redraw lines.

Short Cuts

Place the cursor over the bottom right corner of an object. After the cursor changes shape to an arrow, click the left mouse button and drag the bracket to the new object size.

You may resize an object before you place it on the work area by positioning the outline rectangle at the desired location, pressing the left mouse button, then dragging the arrow pointer to the position you want for the lower right corner of the object. Release the mouse button and you have the size and placement you need.

Location

On the object menu [image] Size

See Also

Object Menu.


Sliding Collector

An object that outputs an Array 1D.

Use

Use Sliding Collector to create an Array 1D from scalar input data.

Object Menu

Clear - Clears the contents of the Sliding Collector.

Open View Parameters

Array Size - The number of elements in the output array. Array Size can be a data input. Default is 10.

Trigger Every - The number of times the input pin must be activated before an array is output. Default is 10.

Both parameters may be set from the open view or from data input pins. Parameters must be integers.

Enum inputs are converted to type Text before the data is placed into the array.

Notes

Sliding Collector builds an Array 1D by automatically sequencing through the array index. Generally, Array Size and Trigger Every are the same size.

The output array is always an Array 1D of length Array Size. The type of the output array is determined by the first input data after a Clear.

If Trigger Every is smaller than Array Size, Sliding Collector generates intermediate outputs. For example, if Array Size is 4 and Trigger Every is 2, the Sliding Collector outputs an array four long after two data inputs. The first two elements of the output are the data elements input; the last two elements of the output are 0.

If Trigger Every is larger than Array Size, some of the input elements are discarded. For example, if Array Size is 2 and Trigger Every is 4, the output is an array two long with the last two pieces of data in it. The first two pieces of data input are discarded.

Location

Data [image] Sliding Collector

See Also

Allocate Array, Collector, Concatenator, Get Values, Set Values., Properties (Object), and Object Menu

To Collect Data into an Array


Specify Object Type

A dialog box that lets you specify optional details when declaring a variable for an ActiveX automation object, control, or a .NET object.

Use

Use the Specify Object Type dialog box to set the Library and Class, and control events when declaring a variable for an ActiveX object. Also use Specify Object Type dialog box to set the Assembly, Namespace, and Type when declaring a variable for a .NET object. Before you can declare variables for ActiveX or .NET objects you must make them available to VEE. For ActiveX objects use Device [image] ActiveX Automation References or ActiveX Control References… For .NET objects use Device [image] .NET Assembly References.

Declaring variables for ActiveX objects is optional, as it is for all other variables. However, by declaring variables for ActiveX objects, and specifying the object type details, VEE will do type checking automatically to assure that the specified Library and Class are assigned only to the declared variable.

Declaring an automation object variable does not actually create the object for you. For an automation object, you must still use the CreateObject function in a Formula expression to create the object for use in a program. The following expression is an example:

Set Excel = CreateObject("Excel.Application")

Similarly, declaring a .NET object variable does not actually create the object for you. To create a .NET object, you must still use the CreateInstance function in a Formula expression to create the object for use in a program. The following expression is an example:

Set hashtable = CreateInstance("mscorlib", "System.Collections.Hashtable");

Dialog Information

ActiveX Object

Library: - Click in this area for a drop-down list of available ActiveX libraries. This list is made available when you select them using Device [image] ActiveX Automation References… and ActiveX Control References…

Class: - Click in this area for a drop-down list of available classes. The list contains those classes contained in the selected library.

Enable Events - This field is active if the selected class contains events. If you want to handle events in your program that are generated by an ActiveX object, click on this choice so a check mark appears. If you enable this choice, be sure to create an event-handler UserFunction (object menu [image] Create Event Handler).

OK - Once you have specified the object type, click OK for the choices to take effect in the Declare Variable object.

.NET Object

Assembly: - Click in this area for a drop-down list of available .NET Assemblies. This list is made available when you select them using Device [image] .NET Assembly References…

Namespace: - Click in this area for a drop-down list of available namespaces. The list contains those namespaces contained in the selected assembly

Type: - Click in this area for a drop-down list of available types. The list contains those types contained in the selected namespace.

Notes

If you enabled events when declaring an ActiveX object variable, the Declare Variable object displays Events: Enabled. You must create an event-handler UserFunction. It is easy to do this when you declare the variable by using the Create Event Handler… menu pick in the Declare Variable object menu.

VEE handles .NET object events as long as the events are coming from the same thread that created the .NET object. You may enable .NET object events when declaring a .NET object variable.

Location

Data [image] Variable [image] Declare Variable
(set Type to Object, Set Sub-Type, then click Edit…)

See Also

ActiveX Automation References, ActiveX Control References, Declare Variable.

See Help => Contents and Index => Tell Me About...=> Active X for details about using ActiveX objects and controls in VEE. See Help => Contents and Index => Tell Me About...=> .NET Framework for details about using .NET.


Spectrum (Freq)

A menu item that contains frequency-domain displays.

Use

Use Spectrum (Freq) to access the following frequency-domain displays:

Magnitude Spectrum

Phase Spectrum

Magnitude vs Phase (Polar)

Magnitude vs Phase (Smith)

Notes

Inputs must be Waveform, Spectrum, or an array of Coords.

If a Waveform is input to a Spectrum display, it is automatically transformed into a Spectrum by way of a Fast Fourier Transform (fft).

Location

Display [image] Spectrum (Freq)

See Also

Magnitude Spectrum, Magnitude vs Phase, Phase Spectrum, and Waveform (Time).


Split

Splits a string into two pieces. For example, the word ordinary split on the letter i. Two sub-strings would result: ord and nary. The letter i is destroyed.

Location

System [image] String [image] Split


Stack - Clear

Removes all items from the stack.

Location

System [image] Collections [image] Stack [image] Clear


Stack - Count

Counts the items in the stack.

Location

System [image] Collections [image] Stack [image] Count


Stack - Create

Creates a memory stack.

Location

System [image] Collections [image] Stack [image] Create


Stack - Enumerate

Create a listing of the items in the stack.

Location

System [image] Collections [image] Stack [image] Enumerate Items


Stack - Peek an Item

Peek at an item on the stack.

Location

System [image] Collections [image] Stack [image] Peek Item


Stack - Pop an Item

Pop an item off of the stack.

Location

System [image] Collections [image] Stack [image] Pop Item


Stack - Push Item

Push item onto the stack.

Location

System [image] Collections [image] Stack [image] Push Item


Start

An object that, when its button is pressed, starts the execution of a thread.

Use

The Start object, when its button is pressed, begins the execution of the thread to which it is connected, but has no effect on other threads. (Pressing Run starts the execution of all threads in the program, regardless of whether they have Start objects.)

Notes

If a program includes more than one independent thread, you can use Start to initiate a single thread without running the other threads.

When you press Run or Start, propagation begins with Start object(s). If more than one Start object is on a thread, propagation begins at each Start and proceeds in parallel as far as allowed by the propagation rules.

If you press Start inside a UserObject, the UserObject runs but its data output pins do not activate; therefore, propagation does not continue.

Location

Flow [image] Start

See Also

Raise Error, Exit Thread, Exit UserObject, Stop, and Properties (Object)

To Start a VEE Program


Starts With

If the string starts with the sub-string you provide, a boolean true is returned.

Location

System   [image] String [image] Starts With


Status Bar

A toggle function on the View menu which controls the visibility of the VEE Status Bar.

Use

Use Status Bar to turn the VEE status bar on or off. A checkmark will appear to the left of the Status Bar menu selection when it is turned on.

The Status Bar is a message box located at the bottom of the VEE workspace. The Status Bar displays a variety of useful information, including:

A display of file-load progress and the name of the file being loaded.

Descriptive text for each item on an VEE pull-down menu.

Descriptive text for each button on the VEE Toolbar.

Displays temporary information such as X,Y coordinate data while you are positioning an object in the VEE workspace. It will also provide object Width and Height information for sizing the object.

Constant visible status on the execution mode of the VEE program.

Constant visible status on the state of the VEE Profiler.

Indicates whether or not the VEE program has been modified.

Provides a variety of other temporary status messages such as "File Saved" or "3 objects selected", etc.

Location

View [image] Status Bar

See Also

Toolbar


Step Into

Executes a program by operating one primitive object at a time.

Use

Use Step Into to debug your program. Step Into operates one primitive object every time it is selected. The next object to execute has a yellow border (by default).

When a UserObject or local or imported UserFunction is encountered, VEE will put the object into its detail view and execute each of its objects.

Notes

Step Into will not open remote, built-in, or compiled functions. Step Into will open UserFunctions called from Formula objects and Call objects, but not from transaction objects.

Step Into will only work in a UserFunction or a UserObject when the UserFunction or UserObject is time-sliced. A UserFunction will time-slice only when called from Call, Formula, If/Then/Else, or Sequencer objects (only from the Function field). A UserFunction will not time-slice when called from a To File, To String, or similar object, or if the formula is supplied via a control pin.

In VEE 4 and higher execution modes, a UserObject will only time-slice when invoked from separate threads.

Step Into is not available from a secured program.

PreRun occurs the first time you select Step Into.

Short Cut

F11 maps to Debug [image] Step Into

Location

Debug [image] Step Into

See Also

Call Stack, Step Over, Step Out, Default Preferences, Pause, Run/Resume, Run, Show Data Flow, Show Execution Flow, Start, Stop, and Toggle Breakpoint.

To Step through a Program


Step Out

Completes execution of the current UserObject or UserFunction, and pauses on the next object.

Use

Use Step Out to debug your program. Step Out operates one primitive object every time it is selected. The next object to execute has a yellow border (by default).

If the execution is in a UserObject or UserFunction, VEE will complete execution of all of the objects in that UserObject or UserFunction and exit the UserObject or UserFunction.

Notes

Step Out is not available from a secured program.

PreRun occurs the first time you select Step Out.

Short Cut

Shift-F11 maps to Debug [image] Step Out

Location

Debug [image] Step Out

See Also

Call Stack, Step Into, Step Over, Default Preferences, Pause, Run/Resume, Run, Show Data Flow, Show Execution Flow, Start, Stop, and Toggle Breakpoint.

To Step through a Program


Step Over

Executes a program by operating one primitive object at a time, without opening UserObjects or UserFunctions.

Use

Use Step Over to debug your program. Step Over operates one primitive object every time it is selected. The next object to execute has a yellow border (by default).

When a UserObject or UserFunction is encountered, VEE will execute the object in its entirety.

Notes

Step Over is not available from a secured program.

PreRun occurs the first time you select Step Over.

Short Cut

F10 maps to Debug [image] Step Over

Location

Debug [image] Step Over

See Also

Call Stack, Step Into, Step Out, Default Preferences, Pause, Run/Resume, Run, Show Data Flow, Show Execution Flow, Start, Stop, and Toggle Breakpoint.

To Step through a Program


Stop

Stops all threads in a program.

Use

Use Stop to stop program execution. After Stop is selected, press Resume to continue execution.

Notes

When Stop is selected, the program goes to the "stopped" state which clears any highlighting, and closes any open files and I/O channels.

Location

Debug [image] Stop

See Also

Default Preferences, Pause, Run/Resume, Run, Step Into, Step Over, Step Out, Properties (Object), Stop (Object), and Toggle Breakpoint.

To Step through a Program

To Stop a VEE Program


Stop (Object)

An object that stops the execution of a program.

Use

Use Stop to pause the execution of all threads in the program and return an error code. Stop is usually used after testing for a certain condition.

Open View Parameters

Exit Code - A number that indicates the status of the program. You can type the Exit Code in the recessed rectangle or add it as a data input. The Exit Code is an 8-bit integer that is output to the operating system; if the output is greater than 255, it is output modulo 256 (256 is output as 0).

If you run VEE with the -r option, Stop exits VEE.

Location

Flow [image] Stop

See Also

Exit Thread, Exit UserObject, Raise Error, Start, and Stop.

To Stop a VEE Program


String - Add

Adds a string to a string collection.

Location

System [image] Collections [image] StringCollection [image] Add String


String Collection - Clear

Clear all string items in a given collection.

Location

System [image] Collections [image] StringCollection [image] Clear StringCollection


String Collection - Create

Creates a collection of string items.

Location

System [image] Collections [image] StringCollection [image] Create


String - Contains String?

Searches a given string collection for a given string value.

Location

System [image] Collections [image] StringCollection [image] Contains String?


String - Count

Counts the number of strings in a string collection.

Location

System [image] Collections [image] StringCollection [image] Count


String - Get

Gets a string from a given collection at a given index.

Location

System [image] Collections [image] StringCollection [image] Get String


String - Get All

Gets all strings from a given collection.

Location

System [image] Collections [image] StringCollection [image] Get All Strings


String - Remove

Removes a string from a string collection.

Location

System [image] Collections [image] StringCollection [image] Remove String


Set String

Sets the string value at a given index for a given collection.

Location

System [image] Collections [image] StringCollection [image] Set String


String Compare

Compares two string values. Case can be tested also.

Location

System [image] String [image] Compare


Strip Chart

An object that displays continuously-generated data.

Use

Use Strip Chart to display the recent history of data that is continuously generated. For each y input value, the x value is incremented by the specified Step size. When new data runs off the right side of the display, the display automatically scrolls to show you the latest data.

Strip Chart saves all data sent to it until it's cleared, unless the buffer size is set to a finite value.

Unlike other graphical displays, array data will be appended to the end of the Strip Chart trace, rather than first clearing the trace.

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Y name - The name of the Y axis.

Trace1 - The name of the first trace.

Step Size: - Distance between data points on the X axis.

X name - The name of the X axis.

Object Menu

Auto Scale [image] - Clicking these menu items immediately rescales the display to show the entire trace. (Can be added as control pins.)

Auto Scale - Automatically scales both axes.

Auto Scale X - Automatically scales the X axis.

Auto Scale Y - Automatically scales the Y axis.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets the display to show the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input. The Next Curve Control Pin is not allowed with Matrix-Input graphs, see Matrix-Input graphs.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Y-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints or plots a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When the property is True, the display is cleared at PreRun time. Default is True.

 ClearAtActivate - When the property is True, the display is cleared at Activate time. Default is True.

 MatrixInput - When this property is True, the Strip Chart would accept a 2D Array (up to a max of 255 rows) as Input data and display multiple traces at the same time. A Strip Chart object is called a Matrix-Input graph if it's MatrixInput property is set to True.

This MatrixInput property can be set to True only if there is no Next Curve Control Pin and the Strip Chart has one single input data pin. Similarly, additional data inputs cannot be added to Matrix-Input graphs.

The MatrixInput property is not available in Panel View, and cannot be toggled at runtime programmatically.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EnableEditTracesAndScales to control the edit-button function of the trace legends. Default is True.

 ShowScalesLegend - In the open view, controls visibility of the scale names. Use EnableEditTracesAndScales to control the edit-button function of the scale legends. Default is True.

 ShowScaleLabels - In the open view, controls visibility of the values labeling the scale axes. Default is True.

 Show Scroll Bars - In the open view, controls visibility of the scroll bars on the X and Y scales. Default is True.

 ShowAutoScaleButton - In the open view, controls visibility of the Auto Scale Button. Default is False.

 EnableEditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use ShowTracesLegend and ShowScalesLegend to control visibility of the trace(s) and scale(s) names.

GridType: - None - No grid lines are shown.

Markers Group: - Allows you to find the exact value of a data point on the displayed curve. If the data is plotted on a log scale, the values shown on the marker are the linear data points.

To move markers to a different trace, click on the open view on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

NumMarkers - The number of markers on the graph. None is the default.

MarkerInterpolate - When the property is True, you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

BufferSize - Specifies the number of points stored in memory. Default is 10000.

Display BackColor: - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view. The default Background color is set in Default Preferences on the Colors tab for Screen Element: Graph Background.

Scale Label group:

Text: - Allows you to select the font of the scale labels from the list of available fonts on your system. The default font for scale label text is set in Default Preferences on the Fonts tab for Screen Element: Graph Scale Label Text.

Traces group: (one per trace)

Name: - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Scale: - If you have multiple Y scales, selects which Y scale is to be used for this trace.

Color: - The color of the trace. Each added trace has a different color than the existing traces. Default for the first trace is yellow.

LineStyle - The format of the line connecting data points. Default is a continuous line.

PointStyle - The symbol that marks each data point. To show unconnected data points, select the single dot LineStyle format and the desired PointStyle symbol. Default is a dot.

Scale - If it exists for more than one Y scale, choose which scale this Trace is scaled by.

Scales property: (one per X and Y scale and extra Y scales)

Show Scale: - If you have multiple Y scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name: - The names of the scales appearing in the open view.

Automatic Scaling: - Not adjustable. Default is off. You can add Auto Scale as a control input. You can also rescale the display using Show Auto Scale Button on the General tab, or Auto Scale on the object menu.

Maximum: - The maximum values of the scales.

Minimum: - The minimum values of the scales.

Label Spacing: - Controls which tic marks are labeled with the scale values. Default for X scale is Every Other Tic; default for Y scale(s) is Every Major Tic.

Mapping: - The way the y data is mapped to the display. The mapping may be linear or log. Not adjustable for the X axis. Default is Linear.

Log Cycles: - The maximum number of decades shown (counting down from the maximum y value) when Auto Scale is activated. Log Cycles is only used when the Mapping is Log. Log Cycles is useful when a trace contains a large dynamic range in the data. Default is 4.

Scale Color - The color of any background grid or tic marks. Default is Gray.

Step Size - The distance between data points on the X axis. Available only for the X axis. Default is 1.

ScaleNumberFormat: (a group appears for the X and Y scales, and for any additional Y scales.)

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Sat 01/Jan/1994 17:01:38). Default is Standard.

The X and Y marker values take on the same number format as the scale to which they are attached. The delta marker values for X and Y use the default number format unless you use the Time Stamp format. Then, if both markers 1 and 2 on the X scale, or both markers on the Y scale are using the Time Stamp format, the delta marker values use the Delta Time format.

Notes

When the MatrixInput property is False, Inputs must be Scalar or Array 1D that can be converted to type Real64. Complex, PComplex, and Spectrum values must be "unbuilt" before being input to a Strip Chart.

When the MatrixInput property is True, Strip Charts can accept a 2D Array (up to a max of 255 rows) as Input data and display multiple traces at the same time.

To get the best update speed and largest display area on the Strip Chart, reset certain Properties. Set Grid Type to None. In the Layout area, turn off all choices except those that you require. Set the Buffer Size as small as possible. Set the X scale Maximum value so display scrolling is infrequent.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A Text field named Scale with a value X, Y (or Y1), Y2, or Y3. The Scale field is required. An error occurs if it is omitted.

One or more of the following fields:

Name - Changes the scale name in the open view. Must be a text value.

Min - Sets the X scale minimum. Must be an integer or real value.

Max - Sets the X scale maximum. Must be an integer or real value.

Mapping - Must have a text value of Linear or Log.

AutoScale - Controls automatic scaling. Must have a text value of On or Off.

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties dialog box. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers group. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display's Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the display's Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] Strip Chart

See Also

Complex Plane, Default Preferences, Magnitude Spectrum, Polar Plot, Waveform (Time), XY Trace, and X vs Y Plot.

To Set Markers in the Display, To Get and Set Marker Properties


SubRecord

An object that allows the user to cut out a number of fields from a record.

Use

Use SubRecord to output a subset of the original record, with specified fields "cut" from the record, on the Record output pin. The record to be edited is input on the Record input pin. The list of fields to be "included" or "excluded" in the output record is input on the Fields input pin.

If Include fields is selected in the open view, the output record will consist only of those fields in the Fields input.

If Exclude fields is selected in the open view, the output record will consist of all fields in the original record excluding those listed in the Fields input.

Open View Parameters

Include fields -- (The default mode.) The output record is constructed from the input record with only those fields in the list of field names on the Fields data input pin. This selection toggles with Exclude fields.

Exclude fields -- The output record is constructed from the input record with only those fields that are not in the list of field names on the Fields data input pin.

Notes

The Fields input pin can be a text array consisting of the names of the record fields to include/exclude in the output record.

If you attempt to include/exclude a field that is not in the input record, an error will occur. If you exclude all the fields of the record, a nil output signal is sent.

Note the distinction between the UnBuild Record, SubRecord, and Get Field objects.

The UnBuild Record object has outputs for the Name List and Type List of the input record fields. The other (optional) outputs A, B, etc. of the UnBuild Record object return the same results as would multiple Get Field objects.

The Get Field object works like a Formula object, in that it uses dot syntax (A.B) to unbuild a record. Note that Get Field allows you to unbuild a record of records in one step by using an expression such as A.B.C. This process would require two UnBuild Record objects.

The SubRecord object differs from UnBuild Record and Get Field in that its output is always a record. The SubRecord device allows you to either include or exclude a list of fields from a record to form a subrecord.

Location

Data [image] Access Record [image] SubRecord

See Also

Build Record, From DataSet, Get Field, Record Constant, Set Field, To DataSet, UnBuild Record, and Properties (Object)


Subtract (System Menu)

Subtract

Subtracts one time value from another.

Location

System [image] DateTime [image] Subtract


System Directory

Retrieves the system directory of the host system.

Location

System [image] Environment [image] System Directory


Tank

An object that displays a Scalar numeric value graphically using a color bar inside a graphical tank.

Use

Use Tank to display a numeric value on a analog scale with a color bar inside a graphical tank, and an optional digital numeric field.

Open View

The minimum and maximum values of the Tank are set on the open view of the object by clicking on the present value and typing in a new value. Tic marks and their labels are automatically calculated and displayed. The minimum value must be less than the maximum value.

These values may also be added as control inputs.

Properties

ClearAtPreRun - When this property is True, the contents of the Tank are cleared at PreRun. Default is True.

ClearAtActivate - When this property is True, the contents of the Tank are cleared at Activate. Default is True.

Orientation - Selects how the Tank is displayed. Default is Vertical.

ShowDigitalDisplay - If this property is True, a digital display of the input value is displayed at the bottom of the open view of the object. If the check box is not selected, the digital display is not displayed and the object operates faster. Default is True.

ShowTics - Controls visibility of scale’s tic marks and labels. Default is True.

Logarithmic - When this property is True, changes scale from linear to logarithmic. Default is False.

LabelSpacing - Controls which tic marks are labeled with the scale values. Default is Every Other Tic.

HighColor - Specifies the color used for the highest range (i.e., greater than High Limit).

High Limit - Defines the numeric lower limit for the highest range. This value must be greater than or equal to the Low Limit. You may add this value as a control input, which disables this property's edit field.

MidColor - Specifies the color used for the middle range (i.e., less than or equal to High Limit and greater than Low Limit).

Low Limit - Defines the numeric upper limit for the lowest range. This value must be less than or equal to the High Limit. You may add this value as a control input, which disables this property's edit field.

LowColor - Specifies the color used for the lowest range (i.e., less than or equal to the Low Limit).

NumberFormat:

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

The input data must be scalar and able to be converted to Real64 (Complex, PComplex, Spectrum, and Coord must be first "unbuilt".)

The Low Limit must be less than the High Limit.

To use only 2 ranges of color, set the Low Limit equal to the High Limit.

To use only 1 color, set the Low Color, Mid Color, and High Color to the same color.

Short Cuts

To quickly change the orientation of the Tank, just resize it to the desired shape. It will automatically change orientation.

Location

Display [image] Indicator [image] Tank

See Also

AlphaNumeric, Color Alarm, Fill Bar, Logging AlphaNumeric, Meter, Thermometer, and Object Menu

To Show an Analog Display of Data


Text

An object that outputs a constant string Scalar or Array 1D.

Use

Use Text to set a string constant or to request user input. Click on the entry field to enter a value.

Example

To use Text as a prompt on a panel view, change the name of the Text object to a prompt such as What is your name? The user fills in the requested information in the entry field.

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object.

ArraySize: - When 1D Array is selected, ArraySize sets the length of the array.

 ArraySizeFixed - When this property is True, the array cannot have lines added or deleted. This selection is only available if 1D Array is selected.

 ShowArrayIndices - When this property is True, each line in the entry field is indexed. This selection is only available if 1D Array is selected.

 PasswordMasking - When this property is True, the text in the entry field of the open view is echoed as asterisks (*).

Wait for Input - When this property is True, the object does not operate until the object's value is changed. When the check box is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

AutoExecute - When this property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, AutoExecute is ignored. Default is False.

 InitialValue - Specifies the value to be set. Default value is a null string.

 InitializeAtPreRun - When this property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When this property is True, the Initial Value is set at Activate time. Default is False.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting an initial value is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires a Text value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to a null string. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

There is no interpretation of escaped characters in this constant. Your entry is replicated exactly on the output pin.

Note that the InitialValue field is always a scalar, even if Text is configured to be an array.

Location

Data [image] Constant [image] Text

See Also

Complex, Constant, Coord, Date/Time, UInt8, UInt16, Int16, Int32, Int64, PComplex, Real32, Real64, Selection Control, Boolean, and Toggle Control.

To Use a Data Constant


Text Input

An object that displays a pop-up dialog box that accepts text input.

Use

Use Text Input to prompt the user to enter text, accept the text, and check the text with a user-defined test for validity.

In the pop-up dialog box, when the OK button is pressed, the text input by the user is output on the Value output pin. When the Cancel button is pressed, a 1 is output on the Cancel output pin.

Open View

  • Prompt/Label - The string that prompts the user to fill in the text field. You may add this parameter as a data input. Default is Enter Text:

  • Default Value - The text that is in the dialog's input field before anything is typed. If the user presses OK without typing anything, this text is output. You may add this parameter as a data input. Default is blank.

  • Value Constraint - The equation that tests the input text for validity. You can use any mathematical expression or call a UserFunction. You may add this parameter as a data input. Default is strLen(value)>0; which means it checks for user input of one or more characters - a null string is not acceptable. To accept any value, use the expression 1.

  • Error Message - The text that is output in a message box if the user input does not meet the Value Constraint. You may add this parameter as a data input. Default is You must enter text.

Properties

  • PopupTimeoutEnabled - When this property is True, a Timeout output pin is added to the object. Default is False.

  • PopUpDuration - Sets the length of time the pop-up dialog box is displayed. After this period of time, the dialog box times out and a value of 1 is output on the Timeout output pin. No other outputs pins have data if the Timeout pin executes. This field is only available when the Timeout Enabled check box is selected. Default is 60 seconds.

  • PopupOKLabel - Sets the button label to OK if True. You may also use alternative wording if your users are not native English speakers. Regardless of the wording, the button's function remains the same.

  • PopupCancelLabel - Sets the button label to Cancel if True. You may also use alternative wording if your users are not native English speakers. Regardless of the wording, the button's function remains the same.

  • PopupPasswordMasking - When this property is True, the input text is echoed as asterisks (*). This feature is useful when the operator is entering sensitive data such as a password. The string that is output on the Value output pin is not masked. Default is False.

Notes

The default location of the pop-up dialog box is approximately at the center of the work area. If you move it, next time it will pop-up to the new location.

The title text of the error message dialog box is the same as the Text Input object title.

To respond to the pop-up dialog box using only the keyboard: when the dialog box pops up, start typing and use Enter and Esc keys. Use the Tab key to move between the input field and the buttons and then select the buttons with the Space bar.

The pop-up dialog box and the error dialog box are only displayed while the program is running. While the pop-up dialog box is displayed, the entire program pauses execution, then continues when the dialog box is closed.

Location

Data [image] Dialog Box [image] Text Input

See Also

File Name Selection, Int32 Input, List Box, Message Box, Real64 Input, and UserObject.

To Use a Data Input Dialog Box


Thermometer

An object that displays a Scalar numeric value graphically using a color bar inside a graphical thermometer.

Use

Use Thermometer to display a numeric value on an analog scale with a color bar inside a graphical thermometer, and an optional digital numeric field.

Open View

The minimum and maximum values of the Thermometer are set on the open view of the object by clicking on the present value and typing in a new value. Tic marks and their labels are automatically calculated and displayed. The minimum value must be less than the maximum value.

These values may also be added as control inputs.

Properties

ClearAtPreRun - When this property is True, the contents of the Thermometer are cleared at PreRun. Default is True.

 ClearAtActivate - When this property is True, the contents of the Thermometer are cleared at Activate. Default is True.

Orientation - Selects the orientation of how the Thermometer is displayed. Default is Vertical.

 ShowDigitalDisplay - If this property is True, a digital display of the input value is displayed at the bottom of the open view of the object. If the check box is not selected, the digital display is not displayed and the object operates faster. Default is True.

ShowTics - Controls visibility of scale’s tic marks and labels. Default is True.

Logarithmic - When turned on, changes scale from linear to logarithmic. Default is False.

 LabelSpacing - Controls which tic marks are labeled with the scale values. Default is Every Other Tic.

HighColor - Specifies the color used for the highest range (i.e., greater than High Limit).

 High Limit - Defines the numeric lower limit for the highest range. This value must be greater than or equal to the Low Limit. You may add this value as a control input, which disables this property's edit field.

 MidColor - Specifies the color used for the middle range (i.e., less than or equal to High Limit and greater than Low Limit).

 Low Limit - Defines the numeric upper limit for the lowest range. This value must be less than or equal to the High Limit. You may add this value as a control input, which disables this property's edit field.

 LowColor - Specifies the color used for the lowest range (i.e., less than or equal to the Low Limit).

NumberFormat:

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

Notes

The input data must be Scalar and able to be converted to Real64 (Complex, PComplex, Spectrum, and Coord must be first "unbuilt".)

The Low Limit must be less than the High Limit.

To use only 2 ranges of color, set the Low Limit equal to the High Limit.

To use only 1 color, set the LowColor, MidColor, and HighColor to the same color.

Short Cuts

To quickly change the orientation of the Thermometer, just resize it to the desired shape. It will automatically change orientation.

Location

Display [image] Indicator [image] Thermometer

See Also

AlphaNumeric, Color Alarm, Fill Bar, Logging AlphaNumeric, Meter, Tank, and Object Menu

To Show an Analog Display of Data


Tile Horizontally

A function for managing windows in the VEE workspace.

Use

Use Tile Horizontally to arrange all opened, non-minimized windows as non-overlapping windows. Windows will be stacked one on top of the other.

Location

Window [image] Tile Horizontally

See Also

Cascade, Close All, Minimize All, and Tile Vertically.


Tile Vertically

A function for managing windows in the VEE workspace.

Use

Use Tile Vertically to arrange all opened, non-minimized windows as non-overlapping windows. Windows will be arranged side-by-side in the VEE workspace.

Location

Window [image] Tile Vertically

See Also

Cascade, Close All, Minimize All, and Tile Horizontally.


Timer

An object that outputs the difference in seconds between the activation times of the top and bottom data input pins.

Use

Use Timer to measure how much time passes between two events, such as objects operating. This happens when the first and second inputs are activated. If the second input is activated before the first, the container on the second input is ignored and the Timer object does not execute.

Notes

Time is displayed in seconds.

On Windows, Timer uses the high-resolution performance counter if available on your system.

Location

Device [image] Timer

See Also

Date/Time, Do, Properties (Object), and Object Menu


To

A menu item.

Use

Use To for accessing the following objects which are destinations for I/O operations:

To File

To DataSet

To Printer

To String

Location

I/O [image] To

See Also

From.


To DataSet

An object that allows the user to collect records into a file.

Use

Use To DataSet to collect records that have the same schema definition into a file for later retrieval. The following control pins can be added:

File Name -- This control pin allows the user to change the name of the file that the records will be written to.

Rewind -- This control pin "rewinds" the file and makes it available for rewriting with an entirely new record type. The effect is the same as sending the first record to the file with the Clear File At PreRun selection check box selected.

Close -- This control pin closes the file.

Open View Parameters

To DataSet: -- Click on the name field to display a dialog box, then select the name of the file that contains the DataSet.

Clear File At PreRun -- If this check box is selected, the entire DataSet is cleared and rewritten the first time To DataSet executes (when it receives the first record). Because the DataSet is completely erased, records with a new schema definition can be sent -- the first record establishes the new schema definition.

Notes

The records going into the To DataSet file must have the same schema (data shape and type). The first record written to the file will define the schema that all subsequent records must have.

Every time the To DataSet object executes with its one input (only one input is allowed), the new record is appended to the file. If the new record is an array, every record element of it is appended. The schema (number of fields, and each field name, type, and shape) must match for every record, but the shape of the record (scalar/array) does not matter. The To DataSet object will continue appending to the file until either a Rewind control input is activated, or Clear File At PreRun is selected and PreRun occurs. The next time the To DataSet object executes, it begins writing to the file at its beginning, again starting with the schema of the first record. This schema may be different than what was in the file.

Location

I/O [image] To [image] DataSet

See Also

Build Record, From DataSet, Record Constant, UnBuild Record, Properties (Object), To Write Data to a File, File Open Dialog Box, and Object Menu.


To File

An object that writes data to a file using transaction statements.

Use

Use To File to output a wide variety of encodings and formats to allow flexible output to files. A single pointer is maintained for each file; therefore, data output by different To File objects is written to the file in the order that the objects operated.

To File Actions:

WRITE - Writes data to a file using the specified encoding and format.

EXECUTE - Repositions the file's write pointer to the beginning of the file with (CLEAR) or without (REWIND) erasing the contents of the file. EXECUTE REWIND can only be used when Clear File at PreRun & Open is selected. Note that the file is automatically closed when the VEE program stops. However, you may use the EXECUTE CLOSE transaction to close the file during program execution. EXECUTE DELETE deletes the file.

WAIT - Waits the specified number of seconds before executing the next transaction.

To File Encodings;

TEXT - Writes all data types to human-readable files that are easily edited or ported to other software applications. VEE numeric data is automatically converted to text as it is written.

BYTE - Converts numeric data to binary integer and writes the least significant byte.

CASE - Maps an enumerated value or an integer to a string and writes the string. For example, you could use CASE to accept error numbers and write error messages.

BINARY - Writes all data types in an machine-specific binary format.

BINBLOCK - Writes all VEE data types in binary files with IEEE 488.2 definite length block headers.

CONTAINER - Writes all data types in a VEE specific text format. Use CONTAINER to export data via the "To File" object directly into PV-WAVE to perform visual data analysis.

Open View Parameters

Clear at PreRun & Open - Erases file contents and sets file pointer to the beginning of the file. When the check box is not selected, data is appended to the end of the file.

If you have multiple To File objects pointing to the same file, the check boxes are linked so that if you change it in one place, it changes in all of them.

The open view shows the list of transactions to be executed.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Properties

EolSequence - Specifies the characters sent at the end of WRITE transactions that use EOL ON. The entry in this field must contain zero or more ASCII characters surrounded by double quotes. Default is "\n".

 ArraySeparator - Specifies the character string used to separate elements of an array written by WRITE TEXT transactions. The entry in this field must be surrounded by double quotes.

MultiFieldFormat: Specifies the following two formatting styles for multi-field data types for WRITE TEXT transactions. The affected data types are Coord, Complex, PComplex, and Spectrum.

Data Only - Separates each multi-field item with a comma without surrounding the group with parentheses. The complex number 2+2j would be formatted as 2,2.

(...) Syntax - (default) Separates each multi-field item with a comma and surrounds the group with parentheses. The complex number 2+2j would be formatted as (2,2).

ArrayFormat group: Determines how multidimensional arrays are formatted.

Linear - Arranges array elements linearly.

Block - (default) Arranges array elements in a block of two or more dimensions using the EOL character at the end of each row.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

I/O [image] To [image] File

See Also

Formula, From File, Object Menu, To Write Data to a File, File Open Dialog Box, and To Edit a Transaction


To/From DDE

An object that exchanges data through transactions to and from a Microsoft Windows application that supports Dynamic Data Exchange (DDE).

Use

DDE is a tool for programmers who wish to implement interprocess communication.

You must add one or more transactions to To/From DDE to read or write data. To do this, click on Add Trans in the object menu.

Currently, the .NET Framework is much more fully featured, well documented, and supported.

Otherwise, ActiveX Automation will be more robust for your needs, and is better documented for most servers. For information about ActiveX, see Help => Contents and Index => Tell Me About... => Active X .

Open View Parameters

Application - The name of the Windows application supporting DDE. (For example, Excel.)

Topic - The application-specific identifier for the kind of data. (For example, Sheet1.)

In addition, the open view shows the list of transactions to be executed.

The Application and Topic fields can be added as control inputs.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Properties

EolSequence - Specifies the characters sent at the end of WRITE transactions that use EOL ON. The entry in this field must contain zero or more ASCII characters surrounded by double quotes. Default is "\n".

 ArraySeparator - Specifies the character string used to separate elements of an array written by WRITE TEXT transactions. The entry in this field must be surrounded by double quotes.

MultiFieldFormat group: Specifies the following two formatting styles for multi-field data types for WRITE TEXT transactions. The affected data types are Coord, Complex, PComplex, and Spectrum.

Data Only - Separates each multi-field item with a comma without surrounding the group with parentheses. The complex number 2+2j would be formatted as 2,2.

(...) Syntax - (default) Separates each multi-field item with a comma and surrounds the group with parentheses. The complex number 2+2j would be formatted as (2,2).

ArrayFormat group: Determines how multidimensional arrays are formatted.

Linear - Arranges array elements linearly.

Block - (default) Arranges array elements in a block of two or more dimensions using the EOL character at the end of each row.

Notes

To/From DDE provides for communication with Windows applications that support Dynamic Data Exchange. However, the user is responsible for determining the application-specific protocols necessary for successful DDE communication from VEE to a particular application. This is an advanced programming capability.

A Windows application that supports DDE may act as either a client, a server, or both. However, VEE provides only client capabilities.

To/From DDE uses four types of transactions:

READ(REQUEST) - Reads data from a DDE transfer.

WRITE(POKE) - Writes (pokes) data to a DDE transfer.

EXECUTE - Sends a command to the DDE server that VEE is communicating with. The server then executes the command.

WAIT - Waits for the specified time (in seconds).

To/From DDE initiates and terminates DDE operations as part of its function. You do not need to explicitly initiate and terminate these transactions.

For examples of using DDE, refer to Communicating With Programs .

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

I/O [image] To/From DDE

See Also

Formula, From, From File, To File, To, Object Menu, and To Edit a Transaction


To/From IVI-COM

An object that writes data to and reads data from an instrument using transaction statements which call IVI-COM driver functions.

Use

Download and install the IVI drivers for the instrument you are using. There is a link to the download site within the Instrument Manager.

To automatically configure an IVI-COM driver for your instrument, start the Instrument Manager. In "Auto Discovery" click "Find Instruments". Select the instrument that you want to configure drivers for, and then in "Auto Discovery", click "Configure Drivers". VEE will try to configure all drivers for this instrument. If an IVI-COM driver is found, the "IVI-COM Driver" button will no longer be grayed out.

To manually configure the IVI-COM driver for a particular interface, start the Instrument Manager. Add an instrument and select the interface. From the same Instrument Properties dialog box, select Advanced and then select the IVI-COM Driver tab. Select the IVI-COM driver name that matches your instrument and verify the address of the instrument.

To access the To/From IVI-COM object, bring up the Instrument Manager from the I/O menu. Select an Instrument. Then, in "Create I/O Object", select "IVI-COM Driver". The selection is grayed out if no IVI-COM drivers have been configured for that instrument.

Open View Parameters

The open view shows the list of transactions that can be executed. Each transaction is an IVI-COM command (a call to a function in the IVI-COM driver).

When an empty transaction is double-clicked on, the Select an Operation from... dialog box appears. This dialog box allows you to select the operation to execute. The text area at the bottom of the dialog box gives a description of the currently selected member. The hierarchical tree view of the members shows you the different categories. A member with a + to its left indicates that it has child members. A member with no plus to its left indicates that it has no child members.

CreateInstance is always the first transaction followed by an Initialize transaction. At this point, you can insert the other transactions you want but always remember to end with a Close transaction so the resources are freed.

After you select the operation and click OK, the Edit dialog box appears. This dialog box lets you edit the values for the operation and configure input and output terminals.

Clicking Cancel at this point will cancel the entire selection process.

The Edit dialog box contains the following fields:

Edit Parameters tab:

The parameters vary with the operation selected. In general, the required answers are self-evident.

Configure Terminals tab:

You usually do not need to modify these values.

Clicking OK closes the Edit dialog box and creates the transaction.

When you double-click on an existing transaction, the Edit dialog box will appear, and then you can edit the currently selected call to the function.

Object Menu

Edit Operation - Edits the currently highlighted function.

Add Operation... - Adds a function to the end of the list.

Insert Operation...- Inserts a function before the currently highlighted function.

Cut Operation - Cuts (deletes) the currently highlighted function(s) to the "cut-and-paste" buffer.

Copy Operation - Copies the currently highlighted function(s) to the "cut-and-paste" buffer.

Paste Operation - Pastes the function(s) that had been previously "cut" or "copied" at the pointer location.

Delete Oper- Deletes the currently highlighted function(s) in the list.

Move Oper Up - Moves the currently highlighted function up.

Move Oper Down - Moves the currently highlighted function down.

IVI-COM Help - Gives you the help information associated with the IVI-COM driver. This information was provided by the hardware manufacturer and is included with each driver.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

I/O [image] Instrument Manager...

Notes

On rare occasions the IVI-COM driver will not load. If this occurs, refer to COM Objects - Troubleshooting.

See Also

To/From IVI-COM - Advanced, Object Menu


To/From IVI-COM - Advanced

In the help topic To/From IVI-COM, the basic usage of the To/From IVI-COM method is explained. There are three other ways that this feature can be used. While these are advanced features, you may find them useful in your work.

Uses

Use the Instrument Manager to add a new instrument. Go to the Properties for the instrument and select the Advanced button. Select the IVI-COM Driver tab and choose your IVI-COM driver type. In this tab you will see a box labeled Instrument Interchangeability.

Instrument interchangeability refers to the ability of IVI drivers to work with multiple manufacturers of an instrument so long as the driver and instrument meet the constraints of IVI compatibility. This allows you to switch a Tek scope with an Agilent scope without changing your program, since the calls to the driver and base functionality are standard. It is only when you start using manufacturer specific calls that the instruments are no longer interchangeable.

There are four scenarios for the use of IVI-COM drivers in VEE. Scenario 1 is described in the topic To/From IVI-COM.

Scenario 2

In this scenario, you want to use an IVI-COM driver with a Class Compliant Interface. If you were using a DMM driver, you could now swap IVI compliant DMMs from different manufacturers without changing your program code.

Use the Instrument Manager to add a new instrument. Go to the Properties for the instrument and select the Advanced button. Select the IVI-COM Driver tab and choose your IVI-COM driver type. In this tab you will see a box labeled Instrument Interchangeability. Check the box labeled Use Class Compliant Interface. Checking this box tells VEE that you want to talk to the instrument using only the class compliant interface of the instrument driver.

Scenario 3

In this scenario, you want to use an IVI-COM session. The session is defined in the IVI Config Store and contains the resource information about the instrument.

Use the Instrument Manager to add a new instrument. Go to the Properties for the instrument and select the Advanced button. Select the IVI-COM Driver tab and choose an existing IVI-COM session name. Notice that an IVI-COM session name will have "- Session Name" at the end and that the resource string is grayed out. This is because the session name is used to gather information from the IVI Config Store.

Do not check the Class Compliant Interface checkbox. Leaving the box unchecked tells VEE you want to use an Instrument Specific driver.

If you do not have an IVI-COM session defined, you can define one by pressing the Configure IVI Driver Session button. The application that appears is used to manage your IVI Config Store information. The icon on the top left finds instruments that are directly connected to your computer and reads others that are identified in the IVI Config Store.

Once the instruments have been found, right click on one of them and choose Add Instrument Session to add an IVI session. You must have the IVI driver for this instrument already installed on your computer before you attempt to define a session for it. The wizard that appears takes you through the short number of steps needed to create the IVI session. It is recommended that you change the default name to something more meaningful. Save the configuration. This updates the IVI Config Store.

For more information about how this application works and its other capabilities, please refer to its online help.

Scenario 4

In this scenario, you want to use an IVI-COM session with a Class Compliant Interface. If you were using a DMM driver, you could now swap IVI compliant DMMs from different manufacturers without changing your program code. The session is defined in the IVI Config Store and contains the resource information about the instrument.

Use the Instrument Manager to add a new instrument. Go to the Properties for the instrument and select the Advanced button. Select the IVI-COM Driver tab and choose an existing IVI-COM session name. Notice that the resource string is grayed out. Notice also that an IVI-COM session name will have " - Session Name" appended to the name. This is because the session name is used to gather information from the IVI Config Store.

In this tab you will also see a box labeled Instrument Interchangeability. Check the box labeled Use Class Compliant Interface. If you do not have an IVI-COM session defined, you can select the button Configure IVI Driver Session and follow the instructions described in Scenario 3.

See Also

To/From IVI-COM and Object Menu


To/From NIDAQ

An object that writes data to and reads data from an instrument using transaction statements which call NIDAQ drivers.

Use

Use To/From NIDAQ to communicate with an instrument that has an NIDAQ driver.

To access the To/From NIDAQ object, bring up the Instrument Manager from the I/O menu. Add the NIDAQ interface and choose from NIDMM, NISCOPE, NISWITCH, NIFGEN, NIDAQ, or NIDAQmx. Then, in the "Create I/O Object", select "NIDAQ Driver". The selection is grayed out if no NIDAQ drivers have been configured for that instrument.

Open View Parameters

The open view shows the list of transactions to be executed. Each transaction is a NIDAQ command (a call to a C function in the NIDAQ driver).

When an empty transaction is double-clicked on, the Select a Function Panel dialog box appears.

This dialog box allows you to select the function to execute. The text area at the bottom of the dialog box gives a description of the currently selected function panel. The hierarchical tree view of the functions shows you the different categories of function panels. A folder with a + to its left indicates there are more folders or function panels available. A folder with a - to its left indicates the folders or function panels are shown. To completely expand a branch of the tree, select the item to expand and press the * key.

After selecting the function and clicking OK, the Edit Function Panel dialog box appears. This dialog box lets you edit the values on the function panel, set up variables, and automatically create input and output terminals.

Clicking Cancel at this point will cancel the entire function panel selection process.

The Edit Function Panel dialog box contains the following fields:

Panel tab:

Controls (at the top of the dialog box) - Each control represents a parameter to the function. Editing the value in a control lets you specify a constant value for the parameter. The names of the controls are labels specified from the function panel file. To get help on a control, click the right mouse button on it. There may not be any controls for certain function panels.

Configuration tab: (this tab may not exist for all functions) - Allows you to specify variables for the parameters to the function.

label name group: The name of the control as specified from the function panel file.

Parameter Type: - Specifies the parameter’s type and shape.

Parameter Value: Constant | Variable - Specifies if the parameter is set as a constant value (from the Panel tab) or is input to the C function as a variable. Parameter Value is grayed out if the parameter must be a Variable (such as for an array type). If Variable is selected, the Name and Create Terminal fields are enabled.

Name - The name of the variable passed by the C function. By default, Name is set to the label name as specified from the function panel file. If the variable is an input variable, this field can also contain calls to UserFunctions that return a value (that then would be passed to the function call), variables, and expressions to be evaluated at run time.

Create Terminal - When the check box is selected, the input and/or output terminal is created if it does not currently exist. If the Name field is set to an invalid terminal name (such as a UserFunction call or an expression) this field is grayed out.

Auto-Allocate Input - If the Parameter Type is an array or type Text, memory must be allocated to send to the function to retrieve data. Edit the size field to tell VEE how much memory to allocate to accommodate the number of array elements or string length. It’s important that you set the size large enough. You can uncheck this box and allocate the memory yourself using an input terminal, but this is not recommended.

When you double-click on an existing transaction, the Edit Function Panel dialog box will appear and then you can edit the currently selected call to the function.

Object Menu

Edit Function - Edits the currently highlighted function.

Add Function... - Adds a function to the end of the list.

Insert Function...- Inserts a function before the currently highlighted function.

Cut Function - Cuts (deletes) the currently highlighted function(s) to the "cut-and-paste" buffer.

Copy Function - Copies the currently highlighted function(s) to the "cut-and-paste" buffer.

Paste Function - Pastes the function(s) that had been previously "cut" or "copied" at the pointer location.

Delete Func - Deletes the currently highlighted function(s) in the list.

Move Func Up - Moves the currently highlighted function up.

Move Func Down - Moves the currently highlighted function down.

Instrument Help - Gives you the help information associated with the NIDAQ driver.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Notes

NIDAQ does not support any of the Advanced I/O features.

NIDAQ function calls will not appear in Agilent IO Monitor.

You must allocate memory for array and text parameters passed into the NIDAQ drivers. If not enough memory is allocated for these parameters, the function could overwrite memory and may cause a General Protection Fault or Segmentation Violation. You are strongly encouraged to always use the Auto-Allocate Input feature and be sure to set the memory size large enough.

Since VEE automatically calls init() and close() and takes care of the session handle for you, do not call any init() functions that may be in the driver. See the Advanced I/O help topic for more information.

Some calls to NI-FGEN create handles. These handles require special attention in VEE. See NI-FGEN.

Some calls in NI-SCOPE return waveform data in a manner that is inconsistent with VEE. See NI-SCOPE Fetch/Read Functions.

Location

I/O [image] Instrument Manager...

See Also

Advanced I/O, Component Driver, Formula, Instrument Manager, Panel Driver, To Edit a Transaction, and NI-DAQmx


To/From Socket

An object that uses sockets for I/O within networked computer systems.

Use

Sockets are tools for programmers who want to implement inter-process communication. To/From Socket uses transaction I/O.

You must identify the port you want to connect or bind, and add one or more transactions to To/From Socket to read or write data.

To/From Socket Actions:

READ - Reads data using the specified encoding and format.

WRITE - Writes data using the specified encoding and format.

EXECUTE - Use the EXECUTE CLOSE transaction to specifically terminate a socket connection.

WAIT - Waits the specified number of seconds before executing the next transaction.

To/From Socket Encodings:

TEXT - Reads and writes all data types to human-readable files that are easily edited or ported to other software applications. VEE numeric data is automatically converted to text as it is written.

BYTE - Converts numeric data to binary integer and writes the least significant byte.

CASE - Maps an enumerated value or an integer to a string and writes the string. For example, you could use CASE to accept error numbers and write error messages.

BINARY - Reads and writes all data types in an machine-specific binary format.

BINBLOCK - Reads and writes all VEE data types in binary files with IEEE 488.2 definite length block headers.

CONTAINER - Reads and writes all data types in a VEE specific text format.

Open View Parameters

The open view shows the fields identifying port connections or bindings, the timeout period, and the list of transactions to be executed.

Connect/Bind Port - This button toggles between bind and connect modes. Bind Port binds a socket on the computer on which VEE is running and waits for a connection to occur. Connect Port connects to a bound socket on a remote computer. In the associated text field, enter the port number. Use port numbers between 5000 and 6000.

Host Name - In Bind Port mode, displays the name of host computer on which VEE is running. In Connect Port mode, enter the specific host name or Internet Protocol (IP) address of the remote computer to which you want to connect.

Timeout - Integer value representing the timeout period in seconds allowed for bindings to occur or connections to be accepted. After connections are made, this is the period allowed for all READ and WRITE transactions. Setting this value to zero makes the timeout period infinitely long.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Properties

EolSequence - Specifies the characters sent at the end of WRITE transactions that use EOL ON. The entry in this field must contain zero or more ASCII characters surrounded by double quotes. Default is "\n".

ArraySeparator - Specifies the character string used to separate elements of an array written by WRITE TEXT transactions. The entry in this field must be surrounded by double quotes.

MultiFieldFormat group: Specifies the following two formatting styles for multi-field data types for WRITE TEXT transactions. The affected data types are Coord, Complex, PComplex, and Spectrum.

Data Only - Separates each multi-field item with a comma without surrounding the group with parentheses. The complex number 2+2j would be formatted as 2,2.

(...) Syntax - (default) Separates each multi-field item with a comma and surrounds the group with parentheses. The complex number 2+2j would be formatted as (2,2).

ArrayFormat group: Determines how multidimensional arrays are formatted.

Linear - Arranges array elements linearly.

Block - (default) Arranges array elements in a block of two or more dimensions using the EOL character at the end of each row.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Notes

A To/From Socket object set to bind a socket or make a connection will block all threads in VEE while waiting the allowed timeout period for the connection to occur.

Multiple To/From Socket objects that are binding an identical port number will share the same socket. Likewise, all objects configured with identical port numbers and host names to attempt connection to the same bound socket will share the same socket. The overhead of establishing the connection is incurred in the first execution of one of the commonly configured objects.

Setting the timeout value to zero disables timeouts, making the periods waiting for connections infinitely long. Timeout violations cause errors, and halt VEE execution.

The timeout value is ignored when a connection is attempted if the remote host does not exist or it is down. In this case the VEE interface is frozen until the connection actually fails, which may take up to one minute.

All socket connections established in a VEE program are broken when a program stops executing. When connections are broken, the server and client objects must repeat the bind/connect protocols to re-establish connections.

All READ operations will block for the timeout period waiting for the amount and type of data specified in the transaction. To avoid blocking threads, use the READ IOSTATUS transaction to detect when data is available on the socket.

Location

I/O [image] To/From Socket

See Also

Formula, Object Menu, and To Edit a Transaction


To/From VXIplug&play

An object that writes data to and reads data from an instrument using transaction statements which call VXIplug&play drivers.

Use

Use To/From VXIplug&play to communicate with an instrument that has a VXIplug&play driver. This instrument may be a "rack-and-stack" instrument as well as a VXI instrument.

To access the To/From VXIplug&play object, bring up the Instrument Manager from the I/O menu. Select an Instrument. Then, in the "Create I/O Object", select "Plug&play Driver".The selection is grayed out if no VXIplug&play drivers have been configured for that instrument.

Note that not all VXIplug&play drivers support all platforms. Also certain versions of VTL/VISA (supplied with your GPIB card) may not be supported on all platforms. Please check with the appropriate vendor.

Open View Parameters

The open view shows the list of transactions to be executed. Each transaction is a VXIplug&play command (a call to a C function in the VXIplug&play driver).

When an empty transaction is double-clicked on, the Select a Function Panel dialog box appears.

This dialog box allows you to select the function to execute. The text area at the bottom of the dialog box gives a description of the currently selected function panel. The hierarchical tree view of the functions shows you the different categories of function panels. A folder with a + to its left indicates there are more folders or function panels available. A folder with a - to its left indicates the folders or function panels are shown. f(x) on the left side, indicates a function panel. To completely expand a branch of the tree, select the item to expand and press the * key.

After selecting the function and clicking OK, the Edit Function Panel dialog box appears. This dialog box lets you edit the values on the function panel, set up variables, and automatically create input and output terminals. Click the right mouse button on any non-control area of this dialog box to get help about the function call. Click the right mouse button on any control to get a description of the control.

Clicking Cancel at this point will cancel the entire function panel selection process.

The Edit Function Panel dialog box contains the following fields:

Panel tab:

Controls (at the top of the dialog box) - Each control represents a parameter to the function. Editing the value in a control lets you specify a constant value for the parameter. The names of the controls are labels specified from the function panel file. To get help on a control, click the right mouse button on it. There may not be any controls for certain function panels.

Session Handle - Displays the unique session handle of each instrument.

Status - Displays a non-zero value if an error occurred when executing this function panel.

Function call (at the bottom of the dialog box) - The C function (and its parameters) that are called when the object executes. This command string is also shown as a transaction on the open view of the object.

Configuration tab: (this tab may not exist for all functions) - Allows you to specify variables for the parameters to the function.

label name group: The name of the control as specified from the function panel file.

Parameter Type: - Specifies the parameter’s type and shape.

Parameter Value: Constant | Variable - Specifies if the parameter is set as a constant value (from the Panel tab) or is input to the C function as a variable. Parameter Value is grayed out if the parameter must be a Variable (such as for an array type). If Variable is selected, the Name and Create Terminal fields are enabled.

Name - The name of the variable passed by the C function. By default, Name is set to the label name as specified from the function panel file. If the variable is an input variable, this field can also contain calls to UserFunctions that return a value (that then would be passed to the function call), variables, and expressions to be evaluated at run time.

Create Terminal - When the check box is selected, the input and/or output terminal is created if it does not currently exist. If the Name field is set to an invalid terminal name (such as a UserFunction call or an expression) this field is grayed out.

Auto-Allocate Input - If the Parameter Type is an array or type Text, memory must be allocated to send to the function to retrieve data. Edit the size field to tell VEE how much memory to allocate to accommodate the number of array elements or string length. It’s important that you set the size large enough. You can uncheck this box and allocate the memory yourself using an input terminal, but this is not recommended.

When you double-click on an existing transaction, the Edit Function Panel dialog box will appear and then you can edit the currently selected call to the function.

Object Menu

Edit Function - Edits the currently highlighted function.

Add Function... - Adds a function to the end of the list.

Insert Function...- Inserts a function before the currently highlighted function.

Cut Function - Cuts (deletes) the currently highlighted function(s) to the "cut-and-paste" buffer.

Copy Function - Copies the currently highlighted function(s) to the "cut-and-paste" buffer.

Paste Function - Pastes the function(s) that had been previously "cut" or "copied" at the pointer location.

Delete Func - Deletes the currently highlighted function(s) in the list.

Move Func Up - Moves the currently highlighted function up.

Move Func Down - Moves the currently highlighted function down.

Instrument Help - Gives you the help information associated with the VXIplug&play driver. This information was provided by the hardware manufacturer and is included with each driver.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Properties

IgnoreCautionsReturned - When the check box is selected, any cautions that are returned from transaction calls to some manufacturers' VXIplug&play drivers will not cause a caution dialog box to pop-up and pause the program. Generally, this check box should only be checked after you have gotten a caution from a VXIplug&play and modified your program to handle the caution condition.

Configured Instrument - Contains non-editable information about which configured name in the Instrument Manager this device is connected to.

Notes

When in the Edit Function Panel dialog box, click the right mouse button on the background of the Panel tab for help on the function panel.

Click the right mouse button on a control for an explanation of the parameter.

VXIplug&play does not support any of the Advanced I/O features. For example, a VXIplug&play driver ignores the live mode setting.

VXIplug&play function calls will not appear in Agilent IO Monitor.

VXIplug&play function calls cannot be mixed with Direct I/O or Instrument Panels to communicate with the same instrument in a program. You can, however, use different types of I/O to different instruments in the same program.

You must allocate memory for array and text parameters passed into the VXIplug&play drivers. If not enough memory is allocated for these parameters, the function could overwrite memory and may cause a General Protection Fault or Segmentation Violation. Since the VXIplug&play shared library is linked directly into VEE, this situation can cause VEE to crash and exit. You are strongly encouraged to always use the Auto-Allocate Input feature and be sure to set the memory size large enough.

Since VEE automatically calls init() and close() and takes care of the session handle for you, do not call any init() or autoconnect() functions that may be in the driver. See the Advanced I/O help topic for more information.

Location

I/O [image] Instrument Manager...

See Also

Advanced I/O, Component Driver, Formula, Instrument Manager, Panel Driver.

To Use a Plug&play Driver Object , and To Edit a Transaction


Toggle Control

Objects that output a 1 (pressed, checked, or selected) or a 0. Toggle Control objects have a variety of display formats, but they all work the same way.

Use

Use Toggle Control objects to set a one or a zero output. Toggle Control objects are commonly used with an If/Then object that contains an A==1 condition.

Properties

Format group: - Specifies the appearance of the Toggle Control object and the method of selecting a choice. The default format is whichever object you chose from the menu.

Button - The choice is made by pressing a button.

Check Box - The choice is made by clicking on a recessed box. A check mark indicates on (1).

Vertical Paddle - A vertical paddle switch. A green dot indicates on (1).

Horizontal Paddle - A horizontal paddle switch. A green dot indicates on (1).

Vertical Rocker - A vertical rocker switch. A green dot indicates on (1).

Horizontal Rocker - A horizontal rocker switch. A green dot indicates on (1).

Vertical Slide - A vertical slide switch. A green dot indicates on (1).

Horizontal Slide - A horizontal slide switch. A green dot indicates on (1).

<Custom> - When selected, you can specify your own bitmaps for on and off. Select the bitmaps from the Custom tab.

Execution group:

Wait for Input - When this property is True, the object does not operate until the object's value is changed. When the check box is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

AutoExecute - When this property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, Auto Execute is ignored. Default is False.

Layout group:

Scaled - If this property is True, the toggle images are scaled to the size of the object. If the property is False, the toggle images are left-justified. Default is False.

Show Caption - When the property is True, the caption on the open view of the object is shown. The caption contains the same text as on the title bar.

Initialization group:

InitialValue - Specifies the value to be set. Default value is 0 (zero).

InitializeAtPreRun - When the property is True, the Initial Value is set at PreRun time. Default is False.

InitializeAtActivate - When the property is True, the Initial Value is set at Activate time. Default is False.

CustomOnPicture - Select the graphical image file you want displayed when the Toggle Control outputs a value of 1.

CustomOffPicture - Select the graphical image file you want displayed when the Toggle Control outputs a value of 0.

Preview - Displays the current graphic images selected.

The directory shown is the bitmaps directory under the installation directory. To choose a file from another directory, press the Browse ... button.

VEE examines the file to determine the file format. The currently supported formats are:

Bitmaps (*.BMP)

GIF87a (*.GIF)

Windows MetaFile (*.WMF)

Portable Network Graphic (*.PNG)

Default bitmaps are located in the bitmaps directory under the VEE program installation directory.

Note

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value. This input requires an Int32 Scalar value. A value of 0 is a toggle off. Any other value is a toggle on.

The Reset input allows you to programmatically set the value to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the toggle position can be changed in the object’s open view.

Location

Data [image] Toggle Control

See Also

Complex, Constant, Coord, Date/Time, Selection Control, If/Then/Else, UInt8, Int16, Int32, PComplex, Real32, Real64, and Text.


Toggle Breakpoint

Sets or clears execution breakpoints at the selected objects.

Use

Use Toggle Breakpoint as a debugging tool to set or clear breakpoints. Select the objects and then select Toggle Breakpoint. This action sets breakpoints on any selected objects without breakpoints, and clears the breakpoint on any selected objects with breakpoints.

Setting a breakpoint on an object stops the execution of the program before this object. To continue execution, press the Resume button on the VEE toolbar; to operate only the object with the breakpoint, press one of the Step buttons.

After the breakpoint is set, the object is highlighted with a colored outline border (orange, by default).

Notes

To set the breakpoint of a single object, use the Breakpoint selection on the object properties window.

When an object has a breakpoint set via Toggle Breakpoint, the Breakpoint selection is checked in the Properties window.

Breakpoints are saved with the program. If you do not want the breakpoints to reappear when the program is opened, use Clear All Breakpoints before saving.

Short Cuts

To toggle breakpoints, highlight the object(s) to set, then press CTRL-B.

Location

Debug [image] Toggle Breakpoint

See Also

Activate Breakpoints, Properties (Object), Clear All Breakpoints, Run/Resume, Select All, Show Data Flow, Show Execution Flow, Step Into, Step Over, and Step Out.

To Control Breakpoints


Toolbar

A toggle function on the View menu which controls the visibility of the VEE Toolbar.

Use

Use Toolbar to turn the VEE toolbar on or off. A checkmark will appear to the left of the Toolbar menu selection when it is turned on.

When the Toolbar is visible, you have shortcut access to a number of VEE programming and debugging functions such as opening a new VEE program file, opening an existing VEE program file, or beginning, pausing and stopping a VEE program's execution.

You can determine the function of a Toolbar button by positioning the mouse cursor over the button; a tool tip will appear below the button. A tool tip is a brief description of the button's function. Simultaneously, a description of the Toolbar button's function will also appear in the Status Bar which is located at the bottom of the VEE workspace.

Location

View [image] Toolbar

See Also

Status Bar.


To Printer

An object that sends data to a printer.

Use

Use To Printer to output data to a printer using a wide variety of encodings and formats.

To Printer Actions:

WRITE - Prints data using the specified encoding and format.

WAIT - Waits the specified number of seconds before executing the next transaction.

To Printer Encodings:

In almost all cases, you should use TEXT or CASE encoding to print data. Other encodings should be used by advanced users only.

TEXT - Writes all data types in human-readable form. VEE numeric data is automatically converted to text as it is written.

BYTE - Converts numeric data to binary integer and writes the least significant byte.

CASE - Maps an enumerated value or an integer to a string and writes the string. For example, you could use CASE to accept error numbers and write error messages.

BINARY - Writes all data types in an machine-specific binary format.

BINBLOCK - Writes all VEE data types in binary files with IEEE 488.2 definite length block headers.

CONTAINER - Writes all data types in a machine-specific text format.

Open View Parameters

The open view shows the list of transactions to be executed.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Properties

EolSequence - Specifies the characters sent at the end of WRITE transactions that use EOL ON. The entry in this field must contain zero or more ASCII characters surrounded by double quotes. Default is "\n".

ArraySeparator - Specifies the character string used to separate elements of an array written by WRITE TEXT transactions. The entry in this field must be surrounded by double quotes.

MultiFieldFormat group: Specifies the following two formatting styles for multi-field data types for WRITE TEXT transactions. The affected data types are Coord, Complex, PComplex, and Spectrum.

Data Only - Separates each multi-field item with a comma without surrounding the group with parentheses. The complex number 2+2j would be formatted as 2,2.

(...) Syntax - (default) Separates each multi-field item with a comma and surrounds the group with parentheses. The complex number 2+2j would be formatted as (2,2).

ArrayFormat group: Determines how multidimensional arrays are formatted.

Linear - Arranges array elements linearly.

Block - (default) Arranges array elements in a block of two or more dimensions using the EOL character at the end of each row.

Notes

If you are printing using a WRITE TEXT transaction, To Printer cannot print ASCII text with embedded control characters. Use the To File object instead, and in the file name text field, enter a port name such as LPT1.

To configure the destination printer, use Print Setup.

When the first To Printer object in a program operates, it starts a print job. The print job is shared by all To Printer objects in the program, therefore their output appears in sequence on the same printout.

The print job remains open until PostRun, or until an EXECUTE CLOSE transaction is executed or the End Job control input on any To Printer is activated. PostRun occurs when all the threads in a program complete execution or when you press Stop twice. You access the End Job control input pin by way of the Add Control Input selection in the object menu.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

I/O [image] To [image] Printer

See Also

Default Preferences, Formula, To, To File, To Send Data to a Printer, and To Edit a Transaction


To String

An object that uses transactions to write formatted text to a string.

Use

Use To String to create formatted text using transactions.

If only one string is generated by the To String transactions, the output container is a string scalar. When more than one string is generated, the output container is an Array 1D.

WRITE transactions ending with "EOL ON" will terminate the current output string, causing the next transaction in the To String list to write data to the next array element in the output container. You cannot specify the data format's separator sequence for the End Of Line (EOL) property.

WRITE Transactions ending with "EOL OFF" will not terminate the output string, causing the characters generated by the next WRITE transaction in the To String list to be appended to the end of the current output string. The last transaction in the To String list will always terminate the output string, regardless of that transaction's "EOL" mode.

To String Actions:

WRITE - Writes data using the specified encoding and format.

WAIT - Waits the specified number of seconds before executing the next transaction.

To String Encodings:

In almost all cases, you should use TEXT encoding to write data.

TEXT - Writes all data types in human-readable form. VEE numeric data is automatically converted to text as it is written.

BYTE - Converts numeric data to binary form and writes the ASCII text equivalent that maps to the least significant byte. For example, the following transaction writes the character A (ASCII 65 decimal):

WRITE BYTE 65

CASE - Maps an enumerated value or an integer to a string and writes the string. For example, you could use CASE to accept error numbers and write error messages.

Open View Parameters

The open view shows the list of transactions to be executed.

Object Menu

Edit Trans - Edits the currently highlighted transaction.

Add Trans... - Adds a transaction to the end of the list.

Insert Trans... - Inserts a transaction before the currently highlighted transaction.

Cut Trans - Cuts (deletes) the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Copy Trans - Copies the currently highlighted transaction(s) to the transaction "cut-and-paste" buffer.

Paste Trans - Pastes the transaction(s) that had been previously "cut" or "copied" at the pointer location.

Delete Trans - Deletes the highlighted transaction(s) in the list.

Move Trans Up - Moves the highlighted transaction up.

Move Trans Down - Moves the highlighted transaction down.

Print Trans - Prints the detailed dialog box that describes the currently highlighted transactions.

Properties

EolSequence - Specifies the characters sent at the end of WRITE transactions that use EOL ON. The entry in this field must contain zero or more ASCII characters surrounded by double quotes. Default is "\n".

 ArraySeparator - Specifies the character string used to separate elements of an array written by WRITE TEXT transactions. The entry in this field must be surrounded by double quotes.

MultiFieldFormat group: Specifies the following two formatting styles for multi-field data types for WRITE TEXT transactions. The affected data types are Coord, Complex, PComplex, and Spectrum.

Data Only - Separates each multi-field item with a comma without surrounding the group with parentheses. The complex number 2+2j would be formatted as 2,2.

(...) Syntax - (default) Separates each multi-field item with a comma and surrounds the group with parentheses. The complex number 2+2j would be formatted as (2,2).

ArrayFormat group: Determines how multidimensional arrays are formatted.

Linear - Arranges array elements linearly.

Block - (default) Arranges array elements in a block of two or more dimensions using the EOL character at the end of each row.

Example

To String is a useful debug tool to explore how TEXT transactions operate. Connect a Logging AlphaNumeric display to the To String output terminal to immediately view the results.

Short Cuts

To quickly insert a transaction, place the cursor on a transaction. Press Insert key to insert a transaction over the transaction where you placed the cursor.

To quickly delete ("kill") a transaction, place the cursor on that transaction and press Delete Key.

To cut a transaction to the "cut-and-paste" buffer press CTRL+X.

To copy a transaction from the "cut-and-paste" buffer press CTRL+C.

To paste a transaction from the "cut-and-paste" buffer press CTRL+V.

To quickly move to the next or previous transaction, press Up Arrow key or Down Arrow key respectively.

Location

I/O [image] To [image] String

See Also

Formula, To, To File, To Convert a Number into a String, and To Edit a Transaction


Type Conversion

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Type Conversion to access the following functions.

asBoolean(x)
asClrType(x, t)
asComplex(x)
asCoord(x)
asInt16(x)
asInt32(x)
asInt64(x)
asPComplex(x)
asReal32(x)
asReal64(x)
asText(x)
asUInt8(x)
asVariant(x)
asVariantBool(x)
asVariantCurrency(x)
asVariantDate(x)
asVariantEmpty(x)
asVariantError(x)
asVariantNull(x)
isVariant(x)
isVariantBool(x)
isVariantCurrency(x)
isVariantDate(x)
isVariantEmpty(x)
isVariantError(x)
isVariantNull(x)
typeName(x)

Location

Device [image] Function & Object Browser [image] Built-in Functions [image] Type Conversion


UInt16

An object that outputs a constant 2-byte unsigned integer scalar or 1D array.

Use

UInt16 is a 16-bit two's complement unsigned integer (0 to 65535). Use UInt16 to set an integer constant or to get user input. Click on the entry field to enter a value.

Example

To use UInt16 as a prompt on a panel view, change the name of the UInt16 object to a prompt such as Enter the number of seconds to delay:. The user fills in the requested information in the entry field.

Type in the formula 12*24 into the UInt16 and it will calculate the result.

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are Scalar and Array 1D.

 ArraySize: - When DataShape 1D Array is selected, Size sets the length of the array.

 ArraySizeFixed - When this property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D Array is selected.

 ShowArrayIndices - When this property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is True.

Wait for Input - When this property is True, the object does not operate until the object's value is changed. When the check box is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When this property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, Auto Execute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When this property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When this property is True, the Initial Value is set at Activate time. Default is False.

NumberFormat:

Global Format - Use the default format. Default is on.

Integer: - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin available on most data constants.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires an integer value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the Initial Value field is always a scalar, even if UInt16 is configured to be an array.

Location

Data [image] Constant [image] UInt16

See Also

Alloc UInt16, Complex, Constant, Coord, Date/Time, Selection Control, Default Preferences, UInt8, Int16, Int32, Int64, PComplex, Real32, Real64, Text, Boolean, and Toggle Control.

To Use a Data Constant


UInt8

An object that outputs a constant 1-byte unsigned integer scalar or 1D array.

Use

Use UInt8 to set an integer constant or to get user input. Click on the entry field to enter a value.

Example

To use UInt8 as a prompt on a panel view, change the name of the UInt8 object to a prompt such as Enter the number of seconds to delay:. The user fills in the requested information in the entry field.

Type in the formula 12*24 into the UInt8 and it will calculate the result.

Properties

DataShape - Sets the initial data shape of the value(s) to be output with this object. Possible values are Scalar and Array 1D.

 ArraySize: - When DataShape 1D Array is selected, Size sets the length of the array.

 ArraySizeFixed - When this property is True, the array cannot have lines added or deleted. This selection is only available if DataShape 1D Array is selected.

 ShowArrayIndices - When this property is True, each line in the entry field is indexed. This selection is only available if DataShape 1D Array is selected. Default is True.

Wait for Input - When this property is True, the object does not operate until the object's value is changed. When the check box is not selected, the object operates as soon as any constraints are met, and the currently selected value is output. Default is False.

 AutoExecute - When this property is True, the object operates and starts the rest of the program when a value is selected. If the program is already running, Auto Execute is ignored. Default is False.

InitialValue - Specifies the value to be set. Default value is 0.

 InitializeAtPreRun - When this property is True, the InitialValue is set at PreRun time. Default is False.

 InitializeAtActivate - When this property is True, the Initial Value is set at Activate time. Default is False.

NumberFormat:

Global Format - Use the default format. Default is on.

Integer: - If Global Format is off, specify the number format for integer numbers to be displayed on this object. The choices are Decimal (e.g. 42), Octal (e.g. #Q52), Hexadecimal (e.g. #H2a), and Binary (e.g. #B00101010). Default is Decimal.

Notes

Initialize is most often used for initializing values inside a UserObject. The other method for setting initial values is the Default Value control pin available on most data constants.

Control inputs may be added for Default Value, Reset, Enable Editing, and Disable Editing.

The Default Value input allows you to programmatically change the current value(s). This input requires an integer value, either a Scalar or an Array 1D. The Constant is reconfigured to match the shape of the incoming data.

The Reset input allows you to programmatically set the value(s) to zero. If the Constant is configured as an Array 1D, all values are set to zero. The actual data on the Reset input is ignored.

The Enable Editing and Disable Editing inputs allow you to programmatically control whether the value can be changed in the object’s open view.

Note that the Initial Value field is always a scalar, even if UInt8 is configured to be an array.

Location

Data [image] Constant [image] UInt8

See Also

Alloc UInt8, Complex, Constant, Coord, Date/Time, Selection Control, Default Preferences, UInt16, Int16, Int32, Int64 PComplex, Real32, Real64, Text, Boolean, and Toggle Control.

To Use a Data Constant


UnBuild Complex

An object that outputs the real and imaginary components of a Complex number as Real64 numbers.

Use

Use UnBuild Complex to extract the real and imaginary components from a rectangular Complex number.

Notes

You can also get the components of a Complex number by using the re(x) and imag(x) functions or objects.

Even if inputs are mapped, the outputs are not.

Location

Data [image] UnBuild Data [image] Complex

See Also

Build Complex, UnBuild Data, UnBuild PComplex, Properties (Object), and Object Menu


UnBuild Coord

An object that outputs the values of a Coord as Real64 numbers.

Use

Use UnBuild Coord to extract the x, y, z ... values of a Coord data type. Additional outputs can be added for the z and other coordinate dimensions. The number of outputs must match the number of coordinate dimensions of the input data.

Location

Data [image] UnBuild Data [image] Coord

See Also

Build Coord, UnBuild Data, Properties (Object), and Object Menu


UnBuild Data

A menu item.

Use

Use UnBuild to access the following data type conversion objects:

Coord

Complex

PComplex

Waveform

Spectrum

Record

Location

Data [image] UnBuild Data

See Also

Access Array, Build Data, UnBuild Complex, UnBuild Coord, UnBuild PComplex, UnBuild Record, UnBuild Spectrum, UnBuild Waveform, and Object Menu


UnBuild PComplex

An object that extracts the magnitude and phase components of a PComplex number and outputs them as Real64 numbers.

Use

Use UnBuild PComplex to extract the magnitude and phase components from a PComplex number.

Notes

You can also get the components of a PComplex number by using the mag(x) and phase(x) functions or objects.

Even if inputs are mapped, the output are not.

Location

Data [image] UnBuild Data [image] PComplex

See Also

Build PComplex, Default Preferences, UnBuild Complex, UnBuild Data, Properties (Object), and Object Menu


UnBuild Record

An object that allows the user to unbuild a record and recover its components.

Use

Use UnBuild Record to extract the data components from a record (A, B, and so forth), and to obtain a Name List and Type List for those components.

The Name List output pin outputs a Text array of all the names of the input record field names.

The Type List output pin outputs a Text array of all the data types of the input record.

The A, B, etc. output pins output the individual data components unbuilt from the record.

Notes

You may add an arbitrary number of output pins to this object. Each output pin name must correspond to a name of a record field. Field names are not case sensitive (lowercase and uppercase letters are equivalent).

Note the distinctions between the UnBuild Record, SubRecord, Get Field, and From DataSet objects.

The UnBuild Record object has outputs for the Name List and Type List of the input record fields. The other (optional) outputs A, B, etc. of the UnBuild Record object return the same results as would multiple Get Field objects.

The Get Field object works like a Formula object, in that it uses dot syntax (A.B) to unbuild a record. Note that Get Field allows you to unbuild a record of records in one step by using an expression such as A.B.C. This process would require two UnBuild Record objects.

The SubRecord object differs from UnBuild Record and Get Field in that its output is always a record. The SubRecord device allows you to either include or exclude a list of fields from a record to form a subrecord.

From DataSet lets you read records from a file of records (a "data set") based on the constraints of a logical expression. For example, you could extract all records that have the value PASS in a record field.

Location

Data [image] UnBuild Data [image] Record

See Also

Build Record, buildRecord(), Declare Variable, From DataSet, Get Field, Record Constant, Set Field, SubRecord, To DataSet, Properties (Object), and Object Menu

To Extract a Field from a Record


UnBuild Spectrum

An object that outputs the PComplex values and frequency range of a Spectrum.

Use

Use UnBuild Spectrum to extract an Array 1D of PComplex values and interval information from a Spectrum.

Open View Parameters

Start/Stop | Center/Span - Changes the values in the outputs that describe the frequency range of the Spectrum.

Location

Data [image] UnBuild Data [image] Spectrum

See Also

Build Spectrum, UnBuild Data, UnBuild Waveform, Properties (Object), and Object Menu


UnBuild Waveform

An object that outputs the amplitude values and time span of a Waveform.

Use

Use UnBuild Waveform to extract an Array 1D of the amplitude values and a real value for the time span from a Waveform.

Notes

The Real64 array output will be unmapped.

Location

Data [image] UnBuild Data [image] Waveform

See Also

Build Waveform, UnBuild Data, UnBuild Spectrum, Properties (Object), and Object Menu


Unpack (Object Menu)

A menu selection, found only in the object menu for a UserObject, which "unpacks" the UserObject. The UserObject disappears, but the objects within it become part of the main context of the program.

Use

Use Unpack to remove a UserObject and place its contents into the main context of the program. Or in the case of a nested UserObject, to place its contents into the context of the UserObject in which the unpacked UserObject resided. The functionality within the UserObject is maintained because the objects that made it up retain their lines of connection within the new context.

Notes

Unpack is the reverse of Create UserObject. If you select objects and execute Create UserObject, those objects and their connections become part of the new UserObject. If you then execute Unpack on the UserObject, the objects are returned to the main context of the program, as if you had never created the UserObject.

Location

On the object menu (UserObjects only) [image] Unpack

See Also

Create UserObject and UserObject.


Until Break

An object that repeats execution of a subthread until a Break is encountered.

Use

Use Until Break to start a set of operations that is repeated until a Break is encountered.

Notes

Execution of the subthread hosted by the Until Break output continues until one of the following occurs:

All objects that can, have operated; the subthread is deactivated. The subthread is reactivated by refiring the Until Break output until a Break object is encountered.

A Break object operates. The subthread is deactivated and the sequence output pin is activated.

A Next object operates. The subthread is deactivated then reactivated by refiring the Until Break output until a Break object is encountered.

Until Break outputs an output execution signal that has a real value of zero.

When the subthread hosted by the Until Break object finishes an iteration, all data containers sent during the previous iteration are invalidated before the next iteration. This prevents "old" data from a previous iteration from being reused in the current iteration. However, if flow branching is present within the iterative subthread, some objects may not execute on every iteration. Thus, data containers sent by those objects may be invalidated before other objects can execute on the data. To obtain the desired propagation in this case, use the Sample & Hold object.

Location

Flow [image] Repeat [image] Until Break

See Also

Break, For Count, For Log Range, For Range, Next, On Cycle, Sample & Hold, and Properties (Object)

To Loop Part of a VEE Program


UserFunction

A user-defined function created from a UserObject or a group of selected objects.

Use

You can create a UserFunction by creating a UserObject and then executing Make UserFunction (refer to UserObject for details). You can also create a UserFunction by selecting a group of objects and using Edit [image] Create UserFunction....

You can use Edit UserFunction to edit the UserFunction once it has been created. UserFunctions exist in the "background" and can be called with Call Function or from certain expressions.

An advantage of making a UserFunction out of a UserObject is that the same UserFunction can be called multiple times within the program, but it exists as source code only in one place.

Object Menu

Edit [image] - A parent menu that leads to the UserFunction's context Edit menu. This menu contains the same choices as the main menu's Edit menu. You can get the pop-up Edit menu by clicking the right mouse button on the UserFunction work area.

The following choices are context sensitive to the UserFunction:

Clean Up Lines - Routes the lines in the UserFunction around objects.

Add To Panel - Creates a panel view for the UserFunction (if a panel view does not currently exist) containing the selected objects.

Create UserObject - Creates a UserObject of the currently selected objects.

Create UserFunction - Creates a UserFunction of the currently selected objects.

Cut - Deletes the UserFunction from VEE and from memory, placing it in the paste buffer. The UserFunction, with its contents, can be pasted into another VEE session. For Windows 2000 and XP, this also places an image of the UserFunction edit window, with its contents, on the Clipboard, ready to paste into other applications.

Copy - Copies the UserFunction to the paste buffer. The UserFunction, with its contents, can be pasted into another VEE session. For Windows 2000 and XP, this also places an image of the UserFunction edit window, with its contents, on the Clipboard, ready to paste into other applications.

Make UserObject - The opposite operation from Make UserFunction. Turns the UserFunction back into a UserObject.

Save Secured Version - Saves a version of the UserFunction which cannot be edited by the user. You will be prompted to enter the name of the secured version which will be saved with a .vee extension.

Locate - Highlights the location of the UserFunction in the Program Explorer.

Generate [image] - Creates one of the following objects containing an expression referencing the UserFunction title. You can place the generated object in another part of the program:

Call creates a Call object.

Formula Call creates a Formula object.

If/Then/Else Call creates an If/Then/Else object.

ShowPanel creates a Formula object with the ShowPanel() function.

HidePanel creates a Formula object with the HidePanel() function.

Calls - Opens the Find Results dialog box containing a list of other UserFunctions called by this UserFunction.

Called By - Opens the Find Results dialog box containing a list of other UserFunctions that call this UserFunction.

Create Panel - Creates a panel view of the UserFunction without any objects added to the panel.

Delete Panel - Deletes the panel view of the UserFunction along with any objects that were added to the panel. The objects deleted with the panel are not deleted from the detail view.

Close - Hides the UserFunction edit window. The UserFunction still resides in memory. You do not need to Close the UserFunction edit window before running the program.

Properties

TrigMode group:

Degrees | Radians | Gradians - specifies the default for trigonometric units used throughout this UserFunction.

 PopupPanelTitle: - Title to be displayed on the panel in the execution window.

 ShowPanelOnExecute - When this property is True, shows the panel view associated with the UserFunction when the UserFunction operates. Default is False.

 PopupMoveable - When this property is True, the pop-up panel is movable by the user. Default is True.

 ShowPopupPanelTitle - When this property is True, the title bar on the pop-up panel is displayed. Default is True.

 ShowPopupPanelBorder - When this property is True, the border around the pop-up panel is displayed. Default is True.

Notes

You can create a library of UserFunctions by creating several UserFunctions, and then saving them all to a file. This library then can be imported into a program using Import Library, and deleted with Delete Library.

Not only can you call a UserFunction with Call Function, but you can call it from any expression whose evaluation is delayed until run time. These include expressions in various objects, such as Formula, If/Then/Else, and Set Values, and expressions in Sequencer and I/O transactions. However, the syntax of function calls in an expression allows only a single return value. Thus, a call to a UserFunction from such an expression will return only the value on the first output. If there are additional outputs (excluding the sequence output) their values will be dropped. If there are no outputs, the returned value will be undefined.

To find the name of a panel that is showing (via showPanel() or ShowPanelonExecute), click the right mouse button on the panel and the panel name will pop up.

If you pass a null through a UserFunction and the requiredType or requiredShape is something other than Any, you will get an error.

UserFunctions with a description have a special icon. In the program explorer and in the title bar, the icon [image] lets you know there is a description because of the red triangle in the upper right corner.

Location

Select the UserFunction name from Edit [image] Edit UserFunction or

from a Call Function object menu [image] Edit UserFunction or

double click on the UserFunction name in the Program Explorer.

See Also

Call, Delete
 Library, Edit UserFunction, Formula,
 hidePanel(), If/Then/Else,
 Import Library, lockPosition(),
 panelPosition(), panelSize(),
 Sequencer, showPanel(),
 unlockPosition(), Remote
 Functions, and UserObject.

To Create a UserFunction from Objects in a Program

To Create a UserFunction in a Program


UserName

Retrieves the name of the user who is currently logged in to the machine.

Location

System [image] Environment [image] User Name


UserObject

An object that may contain other objects.

Use

Use UserObject to logically and physically group objects together. A UserObject constitutes a separate "context" from the root context of a program. You can use multiple UserObjects, or nested UserObjects within a program.

To create the desired UserObject, you can move other objects into the work area of the open view of the UserObject, or you can select objects and use Create UserObject from the Edit menu.

The Make UserFunction item in the object menu allows you to make the UserObject into a UserFunction, which can then be called using the Call Function object, or from certain expressions.

Operation:

A UserObject operates just like any other object -- no objects inside of a UserObject operate until all data inputs to the UserObject are activated. All operations inside of the UserObject must be completed before the data outputs are activated.

When objects inside the UserObject are connected to objects outside the UserObject, input and output pins are automatically created when Create UserObject is selected. To add input and output pins to existing UserObjects, use Add Terminal [image] from the object menu.

Creating a UserFunction:

Once you have created a UserObject, you can use Make UserFunction (see "Object Menu," below) to create a UserFunction with the same functionality. The UserObject will disappear from the screen and will be replaced with a Call Function object containing a call to the new UserFunction and the new UserFunctions window. The UserFunction will be added to the list of available UserFunctions, which exists in the "background" within the program. You can call the UserFunction using the Call Function object, or from certain expressions. You can edit the UserFunction by using Edit UserFunction in the Edit menu.

Object Menu

You can select the object menu of the UserObject from the object menu button, but you cannot select it from within the work area of the UserObject open window. From within the window, the right mouse button provides a pop-up Edit menu, just like the one available in the main window. When the pointer is over an object within the UserObject, the right mouse button gives the object menu for that object. You can also get UserObject object menu by placing the pointer over the borders of the UserObject and clicking the right mouse button.

Edit [image] - A parent menu that leads to the UserObject context Edit menu. This menu contains the same choices as the main menu Edit menu. You can get the pop-up Edit menu by clicking the right mouse button on the UserObject work area.

The following choices are context sensitive to the UserObject:

Clean Up Lines - Routes the lines in the UserObject around objects.

Add To Panel - Creates a panel view (for the UserObject) containing the selected objects.

Create UserObject - Creates a UserObject of the currently selected objects.

Create UserFunction - Creates a UserFunction of the currently selected objects.

Maximize - Resizes the open window of the UserObject to occupy the entire VEE work area. Return to the previous open view size with Restore.

Cut - Deletes the UserObject from the program, placing it in the paste buffer. The UserObject and its contents can be pasted into another VEE session. For Windows 2000 and XP, this places an image of the UserObject edit window, with its contents, on the Clipboard, ready to paste into other applications.

Copy - Copies the UserObject to the paste buffer. The UserObject, with all of its contents, can be pasted into another VEE session. For Windows 2000 and XP, this also places an image of the UserObject edit window, with its contents, on the Clipboard, ready to paste into other applications.

Make UserFunction - Converts the UserObject into a UserFunction. The UserObject will disappear from the work area and it is replaced with a Call Function object containing a call to the new UserFunction. Before you do this operation, enter a unique name into the title field. This name will become the UserFunction name, which will be the name by which Call Function or certain expressions can call the UserFunction. If the name is the original "UserObject" or is not unique, you will be prompted for a function name.

Unpack - Deletes the UserObject, but not the objects contained in it.

Save Secured Version - Saves a version of the UserObject which can not be modified by anyone. You will be prompted to enter the name of the secured version. This secured version will be saved with a .vee extension.

Locate - Highlights the location of the UserObject in the Program Explorer.

Calls - Opens the Find Results dialog box containing a list of UserFunctions called by this UserObject.

Create Panel - Creates a panel view of the UserObject without any objects added to the panel.

Delete Panel - Deletes the panel view of the UserObject along with any objects that were added to the panel. The objects deleted with the panel are not deleted from the detail view.

Close - Hides the UserObject edit window. The UserObject still exists as an icon in the program. You do not need to Close the UserObject edit window before running the program.

Properties

TrigMode group:

Degrees | Radians | Gradians - specifies the default for trigonometric units used throughout this UserObject.

PopUpPanelTitle: - Title to be displayed on the panel in the execution window.

ShowPanelOnExecute - When the check box is selected, shows the panel view associated with the UserObject when the UserObject operates. This is only available after the UserObject panel view has been created (using Create Panel). Default is False.

 PopupMoveable - When this property is True, the pop-up panel is movable by the user. Default is True.

 ShowPopupPanelTitle - When this property is True, the title bar on the pop-up panel is displayed. Default is True.

 ShowPopupPanelBorder - When this property is True, the border around the pop-up panel is displayed. Default is True.

Notes

To create a UserObject of the currently selected objects, use Create UserObject.

It is convenient to save UserObjects of common functions (using Save Objects) to create a library of functions to be used again.

You can create a library of UserFunctions by creating several UserObjects, turning them into UserFunctions, and then saving them all to a file. This library then can be imported into a program using Import Library, and deleted with Delete Library.

To find the name of a panel that is showing (via ShowPanelonExecute), click the right mouse button on the panel and the panel name will pop up.

The panel view of a UserObject may be added to the Main panel view or the panel view of a UserObject that is a surrounding context. In other words, panels can be nested. When panels are added to parent panels, an exact duplicate of the source panel is generated. Whenever the source panel is modified, all duplicate panels are updated as well.

If a UserObject has a description associated with it, it will have a special icon, [image]. Note the red in the upper right corner.

To add a UserObject panel to a parent panel, such as the Main panel:

1. After creating a UserObject and its panel, right-mouse click on the UserObject’s icon view to get its object menu.

2. Click on Restore to get the open view. It appears like a panel view. Do not delete this or you will delete the UserObject from the parent program.

3. Select the UserObject so it is highlighted.

4. Click on the Add To Panel toolbar button (Edit [image] Add To Panel). The UserObject appears in the parent panel.

Location

Device [image] UserObject

See Also

Add To Panel, Call, Create UserObject, Delete Library, Direct I/O, Edit UserFunction, Formula, If/Then/Else, Import Library, Create RunTime Version, Sequencer, and UserFunction.

To Create a UserObject from Objects in a Program

To Create a UserObject in a Program


UTCNow

Retrieves the Universal Time (Greenwich Mean Time) for the system.

Location

System [image] DateTime [image] UTCNow


Variable

A menu item.

Use

Use variable to access the following objects which set and get the values of variables.

Set Variable

Get Variable

Delete Variable

Declare Variable

Notes

A variable that is defined in one context of a program can be used in any other context within the program. For example, you can define a variable with a Set Variable object in the root context of the program, and then include a Get Variable to get that variable in a UserObject. You need to avoid name conflicts throughout the program:

If two or more Set Variable objects attempt to set the same variable (with the same name), the current value will be overwritten as each Set Variable executes. This may result in unexpected behavior if you are unaware that duplicate names exist.

If there is a data terminal variable with the same name as a variable, the data terminal variable will take precedence.

For further information, refer to Help => Contents and Index => Tell Me About... => Variables.

Location

Data [image] Variable

See Also

Default Preferences, Declare Variable, Delete Variable, Get Variable, Set Variable, To Create a Variable, WatchWindow, To Delete a Variable, and To Use a Variable.


Variant

Use

The Variant data type is not a distinct data type. It is used in expressions to indicate that the value it represents can be one of a number of other data types. It is the data type it holds at the moment. Any data type can promote or demote to a Variant, and a Variant can promote or demote according to the data it holds and the rules that data would follow.

If this container is passed to an ActiveX Automation Server or Control, it will be translated as VT_VARIANT instead of the data type inside the Variant container. The Variant type is only needed if the ActiveX Automation method requires a parameter of type VT_VARIANT or ByRef VT_VARIANT.

Example

In the function sin(var), data in the Variant data type (var) could be an integer, a real, or a waveform, depending on the value it is assigned to.

In the expression a=sin(var), a will receive the data type that (var) contained.

Location

The only ways to create a Variant data type are:

Data [image] Variable [image] Declare Variable
and select type Variant; or

Use the asVariant() function.

See Also

asVariant(), Declare Variable.


Vertical Paddle

See Toggle Control.


Vertical Rocker

See Toggle Control.


Vertical Slide

See Toggle Control.


View Detail

Switches the view displayed from the panel view to the detail view.

Use

When pressed, View Detail shows the detail view of the program, UserObject, or UserFunction.

Notes

On UserObjects and UserFuntions, View Detail is only visible after you've created a panel view.

After you've secured a panel view, the View Detail button is not visible.

Location

The title bar of the main VEE window, UserObject, or UserFunction (when an associated panel has been created).

See Also

Add To Panel, View Panel, and Create RunTime Version.

To Add Objects to a Panel

To Delete Objects from a Panel


View Panel

Switches the view displayed from the detail view to the panel view.

Use

When pressed, View Panel shows the panel view you created as an interface to your program on either the main VEE window, a UserObject, or UserFunction.

Notes

On UserObjects or UserFunctions, View Panel is only visible when you've created a panel view.

After you've secured a panel view, the View Panel button is not visible.

Location

The title bar of the main VEE window, UserObject, or UserFunction (when an associated panel has been created).

See Also

Add To Panel, View Detail, and Create RunTime Version.

To Add Objects to a Panel

To Delete Objects from a Panel


View Properties

A View menu item that opens the Properties window.

Use

The purpose of the Properties window is to show the programmer the properties for the object that is currently selected. With only rare exceptions, these properties are available for modification.

Location

View [image] Properties

See Also

Properties (Object)


Virtual Source

A menu item.

Use

Use Virtual Source to access the following virtual signal generators.

Function Generator

Pulse Generator

Noise Generator

Notes

Virtual Source objects output Waveforms.

Location

Device [image] Virtual Source

See Also

Build Arb Waveform, Function Generator, Instrument Manager, Noise Generator, and Pulse Generator.


Watch Window

A View menu item that has four sub-commands, which are Globals, Locals, Terminals, and Variables. Each sub-command brings up a corresponding Watch window. For example, the Globals window shows when you choose View => Watch Window => Globals.

Use

With Watch Window, you can

  • View variables and terminals while the program is being debugged.

  • Edit and continue. You can make changes to your variables and terminals while the program is being debugged. The program can continue execution incorporating any changed values.

  • Locate to an object in detail view. It is convenient to find which object the current variable or terminal belongs to.

  • Copy items in Watch Window to the copy-paste buffer.

Window Information

Watch Window includes four tool windows, Locals, Globals, Watch Terminals, and Watch Variables. Each window has three fields.

  • Name field shows the name or identity of variables or terminals.

  • Value field shows and allows editing of the value of variables or terminals. This feature works for scalar and multi-dimensional arrays.

  • Type field shows the data type and shape of variables or terminals.

Locals window:

Local to Context variables in the active context will appear automatically in the Locals window.

The content of the Locals window will change as the active context changes. Variables will automatically disappear from the Locals window when they are deleted in the active context.

Globals window:

All Declared Global variables and Local to Library Declared variables will appear automatically in the Globals window.

Undeclared variables (e.g., via the Set Variable object) or variables in Imported Libraries will not appear in the Globals window immediately after they are added into a program. An Undeclared variable will appear after the program executes past the Set Variable object; a Global variable in an Imported library will appear after the library is imported by running the program or manually loaded via Import Library object's context menu.

Watch Terminals window:

Terminals can be selectively added to the Watch Terminals window. There are three ways to add a terminal to the Watch Terminals window:

1. Double click on an input or output terminal to open an Input / Output Terminal Information dialog box as below.

Click the Watch button. If a terminal is already in the Watch Terminals window, it will not be added into the Watch Terminals window again.

2. Right-click on an output line to open the Edit Line dialog box as below:

Choose Watch Data. If an output terminal is already in the Watch Terminals window, it will not be added into the Watch Terminals window again.

3. Double click an output line to open a Line Value dialog box as below.

Click the Watch button. If an output terminal is already in the Watch Terminals window, it will not be added into the Watch Terminals window again.

In the Watch Terminal window, the status bar can show some information about the selected terminal, i.e. the terminal's context, name of the device, and the name of the terminal.

The format of the Name in the Watch Terminals window is

{ Object Title - Object ID }.Name of output terminals.

For example, in the following figure, one item in the Watch Window dialog box is {bigNum-M.21}.Int16. "bigNum" is the Object title; "M.21" is the object ID which is consistent with what's in the Properties window. "Int16" is the name of the output terminal.

Watch Variables window:

Variables can be selectively added to the Watch Variables window. There are 4 ways to add a variable to the Watch Variables window:

    1. Double-click and type in the name field in the Watch Variables window,

    2. Right-click the variable to watch in the Locals window or the Globals window, then select Add Watch,

    3. Right-click a Declare Variable object, Set Variable object, or Get Variable object in a VEE program, then select Add Watch,

    4. Right-click the variable to watch in the VEE Program Explorer, then select Add Watch.

Context Menus

Right click in the Locals window or the Globals window to open a context menu as follows.

Right click in the Watch Variable window or the Watch Terminals window to open a context menu as follows

  • Copy -- Copy the selected items (including Name, Value, and Type fields) to the "copy-paste" buffer.

  • Copy Nested -- Copy an array to the "copy-paste" buffer. Copy Nested copies the selected array including all its items, even if the array is not expanded in Watch Window.

  • Locate -- Quickly locate the corresponding variable or terminal in the active context. Locate is a very convenient feature especially when the detail view is large.

  • Reference -- VEE will perform a search using the name of this variable when you choose this command. The search results display in the Find Results window.

  • Select All -- Select all items in the current window.

  • Delete -- Remove the selected variable from the Watch Variables window or the Watch Terminals window.

  • Delete All -- Remove all variables from the Watch Variables window or remove all terminals from the Watch Terminals window.

  • Add Watch -- Add variables into the Watch Variables window.

Note

  • Watch Window sorts all items in alphabetical order.

  • All items in the Watch Terminals window and the Watch Variables window will be saved when Watch Window is closed or VEE program closes. All these saved items will be restored in Watch Window when the Watch Window is reopened. VEE only saves the name field and the type filed of those items. No value will be saved.

Updating and editing values

Values of variables and terminals in the Watch Window will be updated only when a program is paused (e.g., hitting a break point) or stopped.

Values of variables and terminals in the Watch Window can be edited by double clicking the value field of the item you want to edit when a program is paused or stopped. Name and type of variables and terminals cannot be changed.

In the Watch Window, when an item is not editable, the item is grayed out.

Data Types Supported by Watch Window

Data types supported by Watch Window are list in the following table.

Data Type | View | Edit
Boolean | Yes | Yes
UInt8 | Yes | Yes
UInt16 | Yes | Yes
Int16 | Yes | Yes
Int32 | Yes | Yes
Int64 | Yes | Yes
Real32 | Yes | Yes
Real64 | Yes | Yes
PComplex | Yes | Yes
Complex | Yes | Yes
Waveform | Yes | Yes
Spectrum | Yes | Yes
Coord | Yes | Yes
Text | Yes | Yes
Enum | Yes | No
Record | Yes | Yes
.NET | Yes | Yes (partly supported)
COM | Minimal | No
Variant | Minimal | No
Array of Boolean,UInt8,UInt16, Int16, Int32, Int64, Real32, Real64, PComplex, Complex, Coord, Text | Yes | Yes

Shortcuts

Press [image] button on Toolbar.

Location

View [image] Watch Window


Waveform (Time)

An object that displays time-domain information (waveforms) on a two-dimensional graphical display.

Use

Use Waveform (Time) to display Waveforms or Spectrums in the time domain. Spectrums are automatically converted to waveforms by way of an Inverse Fast Fourier Transform (ifft). The X axis is in the sampling units of the input waveform (typically, seconds).

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Mag - The name of the Y axis.

Trace1 - The name of the first trace.

Time - The name of the X axis.

Object Menu

Auto Scale [image] - Clicking these menu items immediately rescales the display to show the entire trace. (Can be added as control pins, or set using the Scales properties tab to automatically rescale the display after data is collected.)

Auto Scale - Automatically scales both axes.

Auto Scale X - Automatically scales the X axis.

Auto Scale Y - Automatically scales the Y axis.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets the display the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Y-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When this property is True, the display is cleared at PreRun time. Default is True.

 ClearAtActivate - When this property is True, the display is cleared at Activate time. Default is True.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EnableEditTracesAndScales to control the edit-button function of the trace legends. Default is True.

 ShowScalesLegend - In the open view, controls visibility of the scale names. Use EnableEditTracesAnd Scale to control the edit-button function of the scale legends. Default is True.

 ShowScaleLabels - In the open view, controls visibility of the values labeling the scale axes. Default is True.

 ShowScrollBars - In the open view, controls visibility of the scroll bars on the X and Y scales. Default is True.

 ShowAutoScaleButton - In the open view, controls visibility of the Auto Scale Button. Default is False.

EditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use Show Traces Legend and Show Scales Legend to control visibility of the trace(s) and scale(s) names.

GridType category:

None - No grid lines are shown.

Tic Marks - Shows tic marks at the major and minor divisions on all four sides of the graph.

Axis - Shows tic marks at the major and minor divisions on the X and Y axes of the graph. If the actual axes are scrolled off the graph area, axis lines are drawn on the edge closest to the axes.

Lines - Shows lines at the major divisions and tic marks at the minor divisions. The X and Y axes are shown as thick lines.

NumMarkers category: - Allows you to find the exact value of a data point on the displayed curve. If the data is plotted on a log scale, the values shown on the marker are the linear data points.

To move markers to a different trace, click on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

Off - No markers are shown. This selection is the default.

One - One marker is available.

Two - Two markers are available.

Delta - Two markers are available and the x and y differences between them are displayed.

 MarkerInterpolate - When the check box is selected, you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

The default marker color is yellow.

DisplayBackColor - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view. The default Background color is set in Default Preferences on the Colors tab for Screen Element: Graph Background.

 Font - Allows you to select the font of the scale labels from the list of available fonts on your system. The default font for scale label text is set in Default Preferences on the Fonts tab for Screen Element: Graph Scale Label Text.

Traces category:

Name: - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Color: - The color of the trace. Each added trace has a different color than the existing traces. Default for the first trace is yellow.

LineStyle: - The format of the line connecting data points. Default is a continuous line.

PointStyle: - The symbol that marks each data point. To show unconnected data points, select the single dot LineStyle format and the desired PointStyle symbol. Default is a dot.

Scales category:

Show Scale: - If you have multiple Y scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name: - The names of the scales appearing in the open view.

Automatic Scaling: - Controls whether the display automatically rescales to show the entire trace immediately after it receives data. Default is On. If this is turned Off, you can rescale the display by using the Auto Scale button on the General tab, in the Layout group, or the Auto Scale command on the object menu.

Maximum: - The maximum values of the scales.

Minimum: - The minimum values of the scales.

Label Spacing: - Controls which tic marks are labeled with the scale values. Default for X scale is Every Other Tic; default for Y scale(s) is Every Major Tic.

Mapping: - The way the x and y data is mapped to the display. The mapping may be linear or log. To make a log-log plot, change both X and Y axes to Log. Default is Linear.

Log Cycles: - The maximum number of decades shown (counting down from the maximum x and y values) when Automatic Scaling is on. Log Cycles is only used when the Mapping is Log. Log Cycles is useful when a trace contains a large dynamic range in the data. Default is 4.

Scale Color - The color of any background grid or tic marks. Default is Gray.

ScaleNumberFormat: (a group appears for the X and Y scales, and for any additional Y scales.)

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Sat 01/Jan/1994 17:01:38). Default is Standard.

The X and Y marker values take on the same number format as the scale to which they are attached. The delta marker values for X and Y use the default number format unless you use the Time Stamp format. Then, if both markers 1 and 2 on the X scale, or both markers on the Y scale are using the Time Stamp format, the delta marker values use the Delta Time format.

Notes

Inputs must be Scalar or Array 1D.

Input data of type Coord is plotted by simply using its x and y values without first being converted to type Waveform.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

When the AutomaticScaling property is True (Scales category), the program executes faster if a complete set of data is sent to the display. Then, the display automatically rescales once. If a program sends one data point at a time to the display, the display may automatically rescale after each data point, which will slow down program execution. In this case, use a Collector object to create an array, then send the array to the display.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed or plotted.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A Text field named Scale with a value X, Y (or Y1), Y2, or Y3. The Scale field is required. An error occurs if it is omitted.

One or more of the following fields:

Name - Changes the scale name in the open view. Must be a text value.

Min - Sets the X scale minimum. Must be an integer or real value.

Max - Sets the X scale maximum. Must be an integer or real value.

Mapping - Must have a text value of Linear or Log.

AutoScale - Controls automatic scaling. Must have a text value of On or Off.

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties window. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers group. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display’s Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the display's Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] Waveform (Time)

See Also

Complex Plane, Magnitude Spectrum, Polar Plot, Strip Chart, X vs Y Plot, XY Trace, and Default Preferences.

To Display a Waveform, To Set Markers in the Display, To Get and Set Marker Properties


What is IVI?

IVI (Interchangeable Virtual Instrument) is a new standard put forth by the IVI Foundation. More information can be found at http://www.ivifoundation.org. The IVI Foundation's goal is to create a driver standard that allows instrument interchangeability while still providing quality and high-performance. Interchangeability means you could write a program for an Arbitrary Waveform Generator (ARB) from Fluke and substitute an Agilent ARB and driver. Your program would still work because the IVI standard for ARB drivers requires ARBs from different manufacturers to support the same exact set of function calls. Of course, there are some limitations to interchangeability.

IVI-C versus IVI-COM

There are two types of drivers currently specified by the IVI Foundation. IVI-C drivers extend the VXIplug&play driver specification and their usage is similar. IVI-COM drivers are similar to ActiveX Controls. Therefore, while the driver functionality of these two is similar, the use model is quite different.

See Also

.NET and IVI Drivers


WhichOS()

An object that outputs the operating system on which Agilent VEE Pro is currently running.

Use

Use whichOS() to determine the operating system on which Agilent VEE Pro is running. Returns one of the following strings:

Windows_2000

Windows XP

Windows Vista

Examples

Agilent VEE Pro for Windows XP on a PC: whichOS() returns Windows_XP.

Notes

The whichOS() object is simply a Formula object initialized without inputs and containing the whichOS() equation. You may also type whichOS() into any other Formula object or expression.

Location

Device > Function & Object Browser

> Built-in Functions > System Information > whichOS

See Also

Formula, whichVersion().


whichVersion()

An object that outputs the version of VEE that is currently running.

Use

Use whichVersion() to determine the version of VEE that is running. This is the same string that appears in the Help [image] About dialog box.

Examples

For VEE version 3.2, whichVersion() returns the text string 3.2.

Notes

The whichVersion() object is simply a Formula object initialized without inputs and containing the whichVersion() equation. You may also type whichVersion() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> System Information
> whichVersion

See Also

Formula and whichOS()


Write to Event Log

Writes VEE error information to the Application event log.

Location

System [image] Write to Event Log


X vs Y Plot

An object that displays a Cartesian plot.

Use

Use X vs Y Plot to graphically display values when separate data information is available for X and Y data. When you print more than one trace, each execution of the X vs Y plot object uses the single X input data with each trace's Y input data, therefore all traces share the same X input data. If you want different X data values, you must build coordinates or mapped arrays for each trace and use the X-Y Trace object.

All inputs must be the same size and shape. Mapping information on the input's data is ignored.

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Y name - The name of the Y axis.

YData1 - The name of the first trace.

X name - The name of the X axis.

Object Menu

Auto Scale [image] - Clicking these menu items immediately rescales the display to show the entire trace. (Can be added as control pins, or set using the Scales properties tab to automatically rescale the display after data is collected.)

Auto Scale - Automatically scales both axes.

Auto Scale X - Automatically scales the X axis.

Auto Scale Y - Automatically scales the Y axis.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets the display to the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input. The Next Curve Control Pin is not allowed with Matrix-Input graphs, see Matrix-Input graphs.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Y-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When this property is True, the display is cleared at PreRun time. Default is True.

MatrixInput - When this property is True, the X vs Y Plot would accept a 2D Array (up to a max of 255 rows) as Input data and display multiple traces at the same time. A X vs Y Plot object is called a Matrix-Input graph if it's MatrixInput property is set to True.

This MatrixInput property can be set to True only if there is no Next Curve Control Pin and the X vs Y Plot has one single input data pin. Similarly, additional data inputs cannot be added to Matrix-Input graphs.

The MatrixInput property is not available in Panel View, and cannot be toggled at runtime programmatically.

ClearAtActivate - When this property is True, the display is cleared at Activate time. Default is True.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EnableEditTracesAndScales to control the edit-button function of the trace legends. Default is True.

ShowScalesLegend - In the open view, controls visibility of the scale names. Use EnableEditTracesAndScale to control the edit-button function of the scale legends. Default is True.

 ShowScaleLabels - In the open view, controls visibility of the values labeling the scale axes. Default is True.

 ShowScrollBars - In the open view, controls visibility of the scroll bars on the X and Y scales. Default is True.

 ShowAutoScaleButton - In the open view, controls visibility of the Auto Scale Button. Default is False.

 EnableEditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use Show Traces Legend and Show Scales Legend to control visibility of the trace(s) and scale(s) names.

GridType category:

None - No grid lines are shown.

Tic Marks - Shows tic marks at the major and minor divisions on all four sides of the graph.

Axis - Shows tic marks at the major and minor divisions on the X and Y axes of the graph. If the actual axes are scrolled off the graph area, axis lines are drawn on the edge closest to the axes.

Lines - Shows lines at the major divisions and tic marks at the minor divisions. The X and Y axes are shown as thick lines.

Markers group: - Allows you to find the exact value of a data point on the displayed curve. If the data is plotted on a log scale, the values shown on the marker are the linear data points.

To move markers to a different trace, click on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

NumMarkers:

Off - No markers are shown. This selection is the default.

One - One marker is available.

Two - Two markers are available.

Delta - Two markers are available and the x and y differences between them are displayed.

 MarkersInterpolate - When this property is True, you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

DisplayBackColor - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view. The default Background color is set in Default Preferences on the Colors tab for Screen Element: Graph Background.

Scale Label Text - Allows you to select the font of the scale labels from the list of available fonts on your system. The default font for scale label text is set in Default Preferences on the Fonts tab for Screen Element: Graph Scale Label Text.

Traces group: (One per trace)

Name: - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Color: - The color of the trace. Each added trace has a different color than the existing traces. Default color for the first trace is yellow.

LineStyle: - The format of the line connecting data points. Default is a continuous line.

PointStyle: - The symbol that marks each data point. To show unconnected data points, select the single dot LineStyle format and the desired PointStyle symbol. Default is a dot.

Scale - If it exists for more than one Y scale, choose which scale this Trace is scaled by.

Scales property: (one per X and Y scale and extra Y scales)

Show Scale: - If you have multiple Y scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name: - The names of the scales appearing in the open view.

Automatic Scaling: - Controls whether the display automatically rescales to show the entire trace immediately after it receives data. Default is on. If this is turned off, you can rescale the display by using the Auto Scale button on the General tab, in the Layout group, or the Auto Scale command on the object menu.

Maximum: - The maximum values of the scales.

Minimum: - The minimum values of the scales.

Label Spacing: - Controls which tic marks are labeled with the scale values. Default for X scale is Every Other Tic; default for Y scale(s) is Every Major Tic.

Mapping: - The way the x and y data is mapped to the display. The mapping may be linear or log. To make a log-log plot, change both X and Y axes to Log. Default is Linear.

Log Cycles: - The maximum number of decades shown (counting down from the maximum x and y values) when Automatic Scaling is on. Log Cycles is only used when the Mapping is Log. Log Cycles is useful when a trace contains a large dynamic range in the data. Default is 4.

Scale Color - The color of any background grid or tic marks. Default is Gray.

ScaleNumberFormat properties: (a group appears for the X and Y scales, and for any additional Y scales.)

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

The X and Y marker values take on the same number format as the scale to which they are attached. The delta marker values for X and Y use the default number format unless you use the Time Stamp format. Then, if both markers 1 and 2 on the X scale, or both markers on the Y scale are using the Time Stamp format, the delta marker values use the Delta Time format.

Notes

When the MatrixInput property is False, the Inputs must be Scalar or Array 1D.

When the MatrixInput property is True, X vsY Plots can accept a 2D Array (up to a max of 255 rows) as Input data and display multiple traces at the same time.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

When the AutomaticScaling property is True (Scales category), the program executes faster if a complete set of data is sent to the display. Then, the display automatically rescales once. If a program sends one data point at a time to the display, the display may automatically rescale after each data point, which will slow down program execution. In this case, use a Collector object to create an array, then send the array to the display.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A Text field named Scale with a value X, Y (or Y1), Y2, or Y3. The Scale field is required. An error occurs if it is omitted.

One or more of the following fields:

Name - Changes the scale name in the open view. Must be a text value.

Min - Sets the X scale minimum. Must be an integer or real value.

Max - Sets the X scale maximum. Must be an integer or real value.

Mapping - Must have a text value of Linear or Log.

AutoScale - Controls automatic scaling. Must have a text value of On or Off.

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties dialog box. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers group. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display's Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the display's Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] X vs Y Plot

See Also

Complex Plane, Magnitude Spectrum, Polar Plot, Strip Chart, Waveform (Time), XY Trace, Default Preferences, and Object Menu

To Display XY Values, To Set Markers in the Display, To Get and Set Marker Properties


XY Trace

An object that displays a two-dimensional Cartesian plot.

Use

Use XY Trace to display mapped arrays or a set of values when y data is generated with evenly-spaced x values. An XY Trace is useful for a quick look at data when you don't need (or have) scaled x data values.

The x value that is automatically generated depends on the data type of the trace data. For example, if trace is a real value, the x values is 0, 1, 2, and so forth. If the trace is a Waveform, the x values are time values.

Open View Parameters

These are the default open view parameters. Their use, and the availability of other parameters, is controlled by selections on the object menu and in the Properties dialog box (object menu [image] Properties).

Y name - The name of the Y axis.

Trace1 - The name of the first trace.

X name - The name of the X axis.

Object Menu

Auto Scale [image] - Clicking these menu items immediately rescales the display to show the entire trace. (Can be added as control pins, or set using the Scales properties tab to automatically rescale the display after data is collected.)

Auto Scale - Automatically scales both axes.

Auto Scale X - Automatically scales the X axis.

Auto Scale Y - Automatically scales the Y axis.

Zoom [image] - Scales the display.

In - Magnifies the display to contain only the rectangular region that you selected with the pointer. You select the region after selecting this feature by dragging on the graph area. This action outlines the information with a "rubber band" box.

Out 2|5|10|20|50|100X - Expands the scales of the display by a factor in both the X and Y directions about the center.

Clear Control [image] - Parameters that specify when to clear the display.

Display - Clears the displayed trace(s). This parameter may be added as a control input.

Next Curve - Resets to display the next curve in a family of curves (data from the next time the display operates) without clearing the previous curve. Next Curve must be selected (or activated) before each new curve in the family. This parameter may be added as a control input. The Next Curve Control Pin is not allowed with Matrix-Input graphs, see Matrix-Input graphs.

Center Markers - If markers are available, brings them to the center of the visible part of the trace. This is useful if you've scrolled the display and markers are not visible.

Add Right Scale - Adds up to two additional Y-axis scales to permit traces to have different scale ranges. After adding a right scale, you may add a terminal for its input (object menu [image] Add Terminal [image] Data Input). Then set its properties using the Traces and Scales tabs on the Properties dialog box.

Print - Presents the Print dialog box. Pressing OK prints a copy of the device's entire display on the selected output device. Print may be added as a control input.

Properties

Declared Name - Assigns a variable name to the display. By entering a name, you can programmatically GET/SET some properties of this object, e.g., read marker values if they are turned on. The variable is an Object data type, and it is local to the context where the display exists. See Notes for details.

ClearAtPreRun - When this property is True, the display is cleared at PreRun time. Default is True.

 ClearAtActivate - When this property is True, the display is cleared at Activate time. Default is True.

MatrixInput - When this property is True, the XY Trace would accept a 2D Array (up to a max of 255 rows) as Input data and display multiple traces at the same time. A XY Trace object is called a Matrix-Input graph if it's MatrixInput property is set to True.

This MatrixInput property can be set to True only if there is no Next Curve Control Pin and the XY Trace has one single input data pin. Similarly, additional data inputs cannot be added to Matrix-Input graphs.

The MatrixInput property is not available in Panel View, and cannot be toggled at runtime programmatically.

ShowTracesLegend - In the open view, controls the visibility of the trace names and colors. Use EnableEditTracesAndScales to control the edit-button function of the trace legends. Default is True.

 ShowScalesLegend - In the open view, controls visibility of the scale names. Use EnableEditTracesAndScales to control the edit-button function of the scale legends. Default is True.

 ShowScaleLabels - In the open view, controls visibility of the values labeling the scale axes. Default is True.

 ShowScrollBars - In the open view, controls visibility of the scroll bars on the X and Y scales. Default is True.

 Show Auto Scale Button - In the open view, controls visibility of the Auto Scale Button. Default is False.

 EnableEditTracesAndScales - In the open view, controls the edit-button function of the trace and scale properties. When enabled, click on an individual trace or scale name to edit its properties. Default is True. Use Show Traces Legend and Show Scales Legend to control visibility of the trace(s) and scale(s) names.

GridType category:

None - No grid lines are shown.

Tic Marks - Shows tic marks at the major and minor divisions on all four sides of the graph.

Axis - Shows tic marks at the major and minor divisions on the X and Y axes of the graph. If the actual axes are scrolled off the graph area, axis lines are drawn on the edge closest to the axes.

Lines - Shows lines at the major divisions and tic marks at the minor divisions. The X and Y axes are shown as thick lines.

Markers group: - Allows you to find the exact value of a data point on the displayed curve. If the data is plotted on a log scale, the values shown on the marker are the linear data points.

To move markers to a different trace, click on the open view on the button to the left of the marker values near the bottom of the display. The button cycles through the different line types and colors of the different traces.

Markers group:

Off - No markers are shown. This selection is the default.

One - One marker is available.

Two - Two markers are available.

Delta - Two markers are available and the x and y differences between them are displayed.

 MarkerInterpolate - When this property is True, you can place markers between the displayed data points. The marker values displayed are calculated by linear interpolation. Default is False.

 MarkerColor - Lets you change the marker color on the display.

BackColor - Allows you to select the color of the display area from a palette. You can select different colors when the display appears in the detail view and the panel view. The default Background color is set in Default Preferences on the Colors tab for Screen Element: Graph Background.

Scale Label group:

Text - Allows you to select the font of the scale labels from the list of available fonts on your system. The default font for scale label text is set in Default Preferences on the Fonts tab for Screen Element: Graph Scale Label Text.

Traces groups: One per trace.

Name - The name of the trace that is displayed to the left of the graph area and the name of the corresponding input terminal.

Color - The color of the trace. Each added trace has a different color than the existing traces. Default for the first trace is yellow.

Line Type - The format of the line connecting data points. Default is a continuous line.

Point Type - The symbol that marks each data point. To show unconnected data points, select the single dot Line Type format and the desired Point Type symbol. Default is a dot.

Scale - If it exists for more than one Y scale, choose which scale this Trace is scaled by.

Scales property (one per X and Y scale and extra Y scales)

Show Scale - If you have multiple Y scales, a selection (using a check box) to specify if the end points and an axis of each additional right scale is displayed to the right of the graph area.

Scale Name - The names of the scales appearing in the open view.

Automatic Scaling - Controls whether the display automatically rescales to show the entire trace immediately after it receives data. Default is on. If this is turned off, you can rescale the display by using the Auto Scale button on the General tab, in the Layout group, or the Auto Scale command on the object menu.

Maximum - The maximum values of the scales.

Minimum - The minimum values of the scales.

Label Spacing - Controls which tic marks are labeled with the scale values. Default for X scale is Every Other Tic; default for Y scale(s) is Every Major Tic.

Mapping - The way the x and y data is mapped to the display. The mapping may be linear or log. To make a log-log plot, change both X and Y axes to Log. Default is Linear.

Log Cycles - The maximum number of decades shown (counting down from the maximum x and y values) when Automatic Scaling is on. Log Cycles is only used when the Mapping is Log. Log Cycles is useful when a trace contains a large dynamic range in the data. Default is 4.

Scale Color - The color of any background grid or tic marks. Default is Gray.

ScaleNumberFormat properties: (a group appears for the X and Y scales, and for any additional Y scales.)

Global Format - Use the default format. Default is on.

Real: - If Global Format is off, specify the number format for real numbers to be displayed on this object. The choices are Fixed (e.g. 98.6000), Scientific (e.g. 9.8600E+01), Engineering (e.g. 98.6000E0), Standard (e.g. 98.6), and Time Stamp (e.g. Wed 01/Jan/2003 17:01:38). Default is Standard.

The X and Y marker values take on the same number format as the scale to which they are attached. The delta marker values for X and Y use the default number format unless you use the Time Stamp format. Then, if both markers 1 and 2 on the X scale, or both markers on the Y scale are using the Time Stamp format, the delta marker values use the Delta Time format.

Notes

When the MatrixInput property is False, Inputs must be Scalar or Array 1D that can be converted to type Real64. You must "unbuild" Complex, PComplex, and Spectrum data before inputting to an XY Trace.

When the MatrixInput property is True, XY traces can accept a 2D Array (up to a max of 255 rows) as Input data and display multiple traces at the same time.

Input data of type Coord is plotted by using its x and y values without first being converted to type Real64.

Add traces with the Add Terminal [image] Data Input object menu selection. Up to 255 traces are allowed.

When the AutomaticScaling property is True (Scales category), the program executes faster if a complete set of data is sent to the display. Then, the display automatically rescales once. If a program sends one data point at a time to the display, the display may automatically rescale after each data point, which can slow down program execution. In this case, use a Collector object to create an array, then send the array to the display.

Adding Control Inputs

You can add a Title control input pin, which sets the title bar name to the specified text value. This allows programmatic control over the title shown when the display is printed.

You can add a Traces control input pin. The control input data must be an array of records (or a record scalar if you only want to control one trace). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A field named TraceNum with an integer value (1 is the first trace). The TraceNum field is required. An error occurs if it is omitted.

One or more of the following fields:

Name

Pen

LineType

PointType

The Name field must have a text value. The Pen, LineType and PointType values must be integers from 0 to n, where 0 draws nothing and n is the number of choices available.

You can add a Scales control input pin to control the scales parameters listed above. The control input data must be an array of records (or a record scalar, if you only want to control one scale). Use a Record Constant or Build Record object to create an array of records; each record must have the following fields:

A Text field named Scale with a value X, Y (or Y1), Y2, or Y3. The Scale field is required. An error occurs if it is omitted.

One or more of the following fields:

Name - Changes the scale name in the open view. Must be a text value.

Min - Sets the X scale minimum. Must be an integer or real value.

Max - Sets the X scale maximum. Must be an integer or real value.

Mapping - Must have a text value of Linear or Log.

AutoScale - Controls automatic scaling. Must have a text value of On or Off.

Refer to Using Records and Using DataSets for further information.

Programmatically Setting and Reading Marker Values

To Programmatically Setting and Reading other properties see To Change Properties Programmatically.

You can programmatically get and set marker values. To prepare the display, open its Properties dialog box. Enter a value for Declared Name. The value for Declared Name implicitly declares an Object variable that is local to the display’s context. Next, turn on a setting in the Markers group. VEE assigns the following properties to the markers’ X and Y positions, including the delta values. (Marker1 points down; Marker2 points up.)

Marker1X (gets the position as a Real64)

Marker1Y (gets the position as a Real64)

Marker2X (gets the position as a Real64)

Marker2Y (gets the position as a Real64)

MarkerDX (gets the position as a Real64)

MarkerDY (gets the position as a Real64)

Marker1 (gets/sets the position as a Coord)

Marker2 (gets/sets the position as a Coord)

The Marker1 and Marker2 properties can be used to read the current marker position or move the marker to a new position. All other marker properties are read-only. If you attempt to move the marker to a coordinate that is not on the trace, the marker will "snap" to the closest point that is on the trace.

In your program, enter one or more expressions in a Formula object to set or read the marker values. Each expression must contain the display's Declared Name and the marker property of interest. Marker property names are not case-sensitive. If the display’s Declared Name is XY, and Delta Markers is turned on, the following expressions will read all the available marker values, assigning them to the variables a through f as Real64 scalars:

a = XY.Marker1X

b = XY.Marker1Y

c = XY.Marker2X

d = XY.Marker2Y

e = XY.MarkerDX

f = XY.MarkerDY

You can assign the Declared Name to a global variable. Add an assignment expression to your program in a Formula object, and declare the global using the Declare Variable object. As an example, assume you declared the variable globalXY as a global, and set its Type to Object. Then, in the context where the display exists, add this expression to your program:

Set globalXY = XY

This lets you read the display’s marker values from another context in the program using an expression such as:

a = globalXY.Marker1X

As you develop a program, you may want to include a way to pause the program so you can manually reposition the markers before the program reads their values. One way to pause a program is to add a Confirm (OK) button between the display’s sequence output and the Formula object’s sequence input. Alternately, you may want to position the markers programmatically. For more detailed information on setting markers programmatically, refer to Programmatic Properties.

Location

Display [image] XY Trace

See Also

Complex Plane, Magnitude Spectrum, Polar Plot, Strip Chart, Waveform (Time), X vs Y Plot, Default Preferences, and Object Menu

To Display XY Values, To Set Markers in the Display, To Get and Set Marker Properties


abs(x)

An object that returns the absolute value of x.

Use

Use abs(x) to obtain the absolute value of the number in a container. x may be any shape and the same shape is returned. For types Complex, PComplex, and Spectrum, the absolute value is the magnitude of the complex number; therefore, a Real64 of the same shape is returned.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Real64 of the same shape
PComplex | Real64 of the same shape
Spectrum | Real64 of the same shape

Example

abs(-34) returns 34.

Notes

Mappings are retained in the result. The largest negative Int32 will cause an error.

Location

Device [image] Function & Object Browser

> Built-in Functions
> Real Parts
> abs

See Also

Complex Parts, mag(x), Real Parts, and signof(x).


acos(x)

An object that returns the arccosine of x.

Use

Use acos(x) to generate the arccosine of the x data, with the result in the range of 0 to PI. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

acos(1) returns 0 with Trig Mode set to Degrees.

acos((1.54308, @0)) returns (0.9999, @1.87079) with Trig Mode set to Radians.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

> Built-in Functions
> Trig
> acos

See Also

acosh(x), cos(x), sin(x), tan(x), Trig, and Default Preferences.


acosh(x)

An object that returns the hyperbolic arccosine of x.

Use

Use acosh(x) to generate the hyperbolic arccosine of the x data. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

acosh(1) returns 0.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> acosh

See Also

acos(x), cosh(x), Trig, sinh(x), and tanh(x).


acot(x)

An object that returns the arccotangent of x.

Use

Use acot(x) to generate the arccotangent of the x data, simply returning atan(1/x). acot(0) will return PI/2. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

The return value will be in the current Trig Mode units.

Example

acot(1) returns 45 with Trig Mode set to Degrees.

acot((1.31303, @PI/2)) returns (1.00, @-1.57079) with Trig Mode set to Radians.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> acot

See Also

acoth(x), atan2(y,x), cos(x), sin(x), tan(x), Trig, and Default Preferences.


acoth(x)

An object that returns the hyperbolic arccotangent of x.

Use

Use acoth(x) to generate the hyperbolic arccotangent of the x data. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

acoth(1.5) returns 0.8047.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> acoth

See Also

acot(x), cosh(x), coth(x), Trig, sinh(x), and tanh(x).


a + b (add)

An object that performs an arithmetic addition on two operands.

Use

Use a + b to add the values of two containers. The two containers may be of any type and of any shape. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type with the same shape as the operands.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

PComplex

Spectrum

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. The addition is only performed on the dependent (last) variable.

Text performs addition as a concatenation. Enums convert to Text for the addition. Note that this addition on two strings is not the same as the concat(x, y) function. With the concat function, concat("hello","there") yields a one-dimensional array, two long ["hello", "there"].

Example

Array plus a scalar: [1, 2, 3] + 3 returns [4, 5, 6].

Two Complex scalars: (2,4) + (1,3) returns (3,7).

Two arrays: [1, 2, 3] + [4, 5, 6] returns [5, 7, 9].

Two Coord scalars: coord(1,3) + coord(1,5) returns coord(1,8).

Two Coord scalars: coord(1,3) + coord(2,5) returns an error.

Two Text: "hello" + "there" returns "hellothere".

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Arithmetic
> +

See Also

concat(x,y), a / b (divide), a * b (multiply), and a - b (subtract).


Ai(x)

An object used to calculate the Airy fractional order Bessel function of x.

Use

Use Ai(x) to find the Fractional order Bessel function Airy of the x. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

For Coord input types, the operation is done on the dependent variable.

Example

Ai(10) returns 0.110475325528986.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> Ai

See Also

Bi(x), j0(x), j1(x), jn(x,n), y0(x), y1(x), and yn(x,n).


a ~= b (almost equal to)

An object that performs an almost equal to operation on two operands.

Use

Use a ~= b to determine whether the value(s) of one container is equal to the value(s) of another container for the first seven decimal digits. The two containers may be of any type and of any shape. Integer, Enum and Text types will be compared exactly. If one of the containers is an array (or a record), the other must be either a scalar or an array (or a record) of the same size and shape. The result is a scalar Int32 with the value 0 or 1. If the first operand is almost equal to the second, the value of the result is 1; otherwise the value is 0.

The operation of X ~= 0 (zero) is meaningless in this context since zero has an infinite number of digits of precision and no order of magnitude. This requires that any comparison to zero match exactly. Therefore, comparing any value X to 0 (zero) will always return a 0 (false) unless X exactly equals 0.

Almost equal to does not perform the same comparison as Device [image] Comparator. The Comparator should be used when comparing waveforms or arrays which contain zeros. The Comparator can derive a value for "virtual zero" from the reference data's magnitude.

If both operands are of type Coord, they must have all their dependent variables match for the first seven decimal digits for the result to be 1. If independent variables do not match, an error is returned. Complex, PComplex, and Spectrum containers must have both parts almost match for the operation to return 1. Enums are converted to Text for the comparison.

Arrays must have all the respective values of both containers almost equal for the operation to return 1.

Example

Two scalars: 3.1234560 ~= 3.1234559 returns 1.

Two scalars: 3.1234560 ~= 3.1234459 returns 0.

A scalar and an array: 3.1234560 ~= [3.1234559, 3.1234562, 3.1234563] returns 1.

A scalar and an array: 3.1234560 ~= [3.1234459, 3.1234562, 3.1234569] returns 0.

Two Complex scalars: (2.12345,3.12345) ~= (2.12344,3.12345) returns 0.

Two Complex scalars: (2.1234567,3.12345) ~= (2.1234566,3.12345) returns 1.

Two Coord scalars: coord(1,3.123456) ~= coord(1,3.123446) returns 0.

Two Coord scalars: coord(1,3.123456) ~= coord(2,3.123456) returns Values for independent variables must match.

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings; otherwise an error is returned.

The test for "almost equal to" is slightly different for Complex and Polar Complex numbers. For two real values (a and b) the test for "almost equal to" is:

a - b <= a * 10E-7

However, for two Complex values (a and b) the test is:

re(a) - re(b) <= mag(a) * 10E-7

where:

re(a) is the real component of a

re(b) is the real component of b

mag(a) is the vector magnitude of a

This test is used for both Complex and Polar Complex numbers to avoid any ambiguity regarding the rectangular or polar treatment of "almost equal."

Location

Device [image] Function & Object Browser

>  Operators
> Comparison
> ~=

See Also

a AND b, a == b (equal to), a > b (greater than), a >= b (greater than or equal to), a < b (less than), a <= b (less than or equal to), NOT a, a != b (not equal to), a OR b, Comparison, and a XOR b.

Comparator, Conditional, and If/Then/Else.


a AND b

An object that performs a logical AND operation on two operands.

Use

Use a AND b to determine whether the value(s) of two containers are both logically true (non-zero). The two containers may be of any type and of any shape. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is an Int32 of the same shape as the operands, with value(s) 0 or 1. If both operands are non-zero, the value of the AND operation is 1; otherwise the value is 0.

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. Only the dependent (last) variable is considered for the AND operation.

For Complex, PComplex, and Spectrum containers, the value of the operand is true if either part is non-zero. Text is true if non-null. Enums are converted to Text for the operation.

If both operands are of type Boolean, the result is a Boolean of the same shape as the operands.

Example

Two Boolean scalars: True AND False returns False.

A scalar and an array: 3 AND [3, 3, 3] returns [1, 1, 1].

A scalar and an array: 3 AND [-3, 0, 3] returns [1, 0, 1].

Two arrays: [1, 2, 3] AND [0, 1, (-1)] returns [0, 1, 1].

Two arrays: (1,@90) AND (1,@85) returns 1.

Two Complex scalars: (2,3) AND (0,1) returns 1.

Two Complex scalars: (0,1) AND (1,0) returns 1.

Two Complex scalars: (0,0) AND (0,0) returns 0.

Two Coord scalars: coord(1,3) AND coord(1,5) returns 1.

Two Coord scalars: coord(1,3) AND coord(2,3) returns an error.

A Text scalar and a scalar number: "too" AND 2 returns 1.

A Text scalar and a scalar number: "" AND 0 returns 0 because one string is null and the other is not ("0").

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Note that the If/Then/Else object requires the expression(s) inside it to evaluate to either a scalar or an array, which is either all zeros or all ones.

Location

Device [image] Function & Object Browser

> Operators
> Logical
> AND

See Also

NOT a, a OR b, Comparison, and a XOR b.

Conditional and If/Then/Else.


Arithmetic

A Category of Operators on the Function & Object Browser tool window.

Use

Use the Arithmetic operators to access the following objects which perform arithmetic functions on two operands:

a + b

a - b

a * b

a / b

a ^ b

a MOD b

a DIV b

Notes

Dyadic operations, which are given two different types, convert the lower type to the higher of the two types. See the type conversion information and the hierarchy of types in help topic "Using Dyadic Operators".

In the dyadic operation example below, adding an array and a scalar performs the operation on each element of the array. The result is an array of the same size and shape as the array operand. For example, a scalar plus a linear array of four elements, 5 + [1, 2, 3, 6], produces the linear array of four elements [6, 7, 8, 11]. The same is true for operations like exponentiation. Thus, 2 ^ [3, 4] produces [8, 16].

Dyadic operations, which are given two arrays, require the operands to be conformant, that is, have the same size and shape. The result is an array with the same size and shape as the operands. The operation is done on an element by element basis. For example, adding two linear arrays of three elements each results in a linear array of three elements long. [1, 2, 3] + [4, 5, 6] produces [5, 7, 9]. If the two arrays are not conformant, the result is an error.

Location

Device [image] Function & Object Browser [image]  Operators [image]  Arithmetic

See Also

a + b (add), a / b (divide), a div b (truncated division), a ^ b (exponent), a mod b (modulo), a * b (multiply), and a - b (subtract).


Array

A Category: of Built-in Functions on the Function & Object Browser tool window.

Use

Use Array to access the following objects which perform various functions on arrays.

init(x,val)

totSize(x)

rotate(x,numElem)

concat(x,y)

sum(x)

product(x)

sort(x)

Location

Device [image] Function & Object Browser [image]  Built-in Functions [image]  Array

See Also

concat(x,y), init(x,val),
 product(x), rotate(x, numElem),
 sort(x, direction, field), sum(x),
 and totSize(x).


asBoolean(x)

An object that converts the x value to a Boolean value. x may be any shape.

Use

Use asBoolean(x) to convert the x data to the data type Boolean. x can be any shape and the same shape is returned. If x is not Zero, asBoolean(x) returns True, otherwise returns False;

Allowed Input Type Return Type

Boolean | Boolean
UInt8 | Boolean
UInt16 | Boolean
Int16 | Boolean
Int32 | Boolean
Int64 | Boolean
Real32 | Boolean
Real64 | Boolean
Text* | Boolean

* If x is of Text type, it can only be "True" or "False".

Example

asBoolean(4.5) returns the Boolean value True.

asBoolean(0) returns the Boolean value False.

asBoolean("True") returns the Boolean value True.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asBoolean

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asComplex(x)

An object that converts the x value to a Complex value.

Use

Use asComplex(x) to convert the x data to the data type Complex. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Complex
UInt16 | Complex
Int16 | Complex
Int32 | Complex
Int64 | Complex
Real32 | Complex
Real64 | Complex
PComplex | Complex
Text | Complex

If x is a Text type, it must contain values that will convert to a Complex.

Example

asComplex(4.5) returns the Complex value (4.5, 0).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asComplex

See Also

asCoord(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asCoord(x)

An object that converts the x value to a Coord value.

Use

Use asCoord(x) to convert the x data to the data type Coord. x must be a 1D array shape and will return the same shape as x. If the array is mapped, the Coord array will use the mappings to generate the x values. If the array is not mapped, the x value will be created starting at 0 and incrementing up by 1.

Allowed Input Type Return Type

UInt8 | Coord
UInt16 | Coord
Int16 | Coord
Int32 | Coord
Int64 | Coord
Real32 | Coord
Real64 | Coord

Example

asCoord([4, 5]) returns the Coord array [(0,4), (1,5)].

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asCoord

See Also

asComplex(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asInt16(x)

An object that converts the x value to an Int16 value. You may also want to consider using round(x) to obtain the rounded value, to the nearest integer, of a container. x may be any shape. The round(x) function returns the closest integer (as the same type) to x. The dividing line is at 0.5, which rounds up.

Use

Use asInt16(x) to convert the x data to the data type Int16. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Int16
UInt16 | Int16
Int16 | Int16
Int32 | Int16
Int64 | Int16
Real32 | Int16
Real64 | Int16
Text | Int16

If x is a Text type, it must contain values that will convert to an Int16.

Example

asInt16(4.5) returns the Int16 value 5.

asInt16(4.25) returns the Int16 value 4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asInt16

See Also

asComplex(x), asCoord(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asInt32(x)

An object that converts the x value to an Int32 value. You may also want to consider using round(x) to obtain the rounded value, to the nearest integer, of a container. x may be any shape. The round(x) function returns the closest integer (as the same type) to x. The dividing line is at 0.5, which rounds up.

Use

Use asInt32(x) to convert the x data to the data type Int32. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Int32
UInt16 | Int32
Int16 | Int32
Int32 | Int32
Int64 | Int32
Real32 | Int32
Real64 | Int32
Text | Int32

If x is a Text type, it must contain values that will convert to an Int32.

Example

asInt32(4.5) returns the Int32 value 5.

asInt32(4.25) returns the Int32 value 4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asInt32

See Also

asComplex(x), asCoord(x), asInt16(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asInt64(x)

An object that converts the x value to an Int64 value. You may also want to consider using round(x) to obtain the rounded value, to the nearest integer, of a container. x may be any shape. The round(x) function returns the closest integer (as the same type) to x. The dividing line is at 0.5, which rounds up.

Use

Use asInt64(x) to convert the x data to the data type Int64. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Int64
UInt16 | Int64
Int16 | Int64
Int32 | Int64
Int64 | Int64
Real32 | Int64
Real64 | Int64
Text | Int64

If x is a Text type, it must contain values that will convert to an Int64.

Example

asInt64(4.5) returns the Int64 value 5.

asInt64(4.25) returns the Int64 value 4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asInt64

See Also

asBoolean(x), asComplex(x), asCoord(x), asInt16(x), asInt32(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asPComplex(x)

An object that converts the x value to a PComplex value.

Use

Use asPComplex(x) to convert the x data to the data type PComplex. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | PComplex
UInt16 | PComplex
Int16 | PComplex
Int32 | PComplex
Int64 | PComplex
Real32 | PComplex
Real64 | PComplex
Complex | PComplex
Text | PComplex

If x is a Text type, it must contain values that will convert to a PComplex.

Example

asPComplex(4.5) returns the PComplex value (4,5, @0).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asPComplex

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asInt64(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asReal32(x)

An object that converts the x value to a Real32 value.

Use

Use asReal32(x) to convert the x data to the data type Real32. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real32
UInt16 | Real32
Int16 | Real32
Int32 | Real32
Int64 | Real32
Real32 | Real32
Real64 | Real32
Text | Real32

If x is a Text type, it must contain values that will convert to a Real32.

Example

asReal32("3.1415") returns the Real32 value 3.1415

asReal32(6) = 6.0

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asReal32

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asReal64(x)

An object that converts the x value to a Real64 value.

Use

Use asReal64(x) to convert the x data to the data type Real64. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Text | Text

If x is a Text type, it must contain values that will convert to a Real64.

Example

asReal64("3.1415") returns the Real64 value 3.1415

asReal64(7) = 7.0

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asReal64

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asText(x)

An object that converts the x value to a Text value.

Use

Use asText(x) to convert the x data to the data type Text. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Text
UInt16 | Text
Int16 | Text
Int32 | Text
Int64 | Text
Real32 | Text
Real64 | Text
Coord | Text
Waveform | Text
Complex | Text
PComplex | Text
Spectrum | Text
Text | Text

Example

asText(3.4) returns the Text value "3.4".

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asText

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asUInt8(x)

An object that converts the x value to an Unsigned Int8 (byte) value. You may also consider using round(x) to obtain the rounded value, to the nearest integer, of a container. x may be any shape. The round(x) function returns the closest integer (as the same type) to x. The dividing line is at 0.5, which rounds up.

Use

Use asUInt8(x) to convert the x data to the data type UInt8. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt8
Int16 | UInt8
Int32 | UInt8
Int64 | UInt8
Real32 | UInt8
Real64 | UInt8
Text | UInt8

If x is a Text type, it must contain values that will convert to a UInt8.

Example

asUInt8(4.5) returns the UInt8 value 5.

asUInt8(4.25)returns the UInt8 value 4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asUInt8

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asUInt16(x)

An object that converts the x value to an Unsigned Int16 (2 bytes) value. You may also consider using round(x) to obtain the rounded value, to the nearest integer, of a container. x may be any shape. The round(x) function returns the closest integer (as the same type) to x. The dividing line is at 0.5, which rounds up.

Use

Use asUInt16(x) to convert the x data to the data type UInt16. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | UInt16
UInt16 | UInt16
Int16 | UInt16
Int32 | UInt16
Int64 | UInt16
Real32 | UInt16
Real64 | UInt16
Text | UInt16

If x is a Text type, it must contain values that will convert to a UInt16.

Example

asUInt16(4.5) returns the UInt16 value 5.

asUInt16(4.25)returns the UInt16 value 4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asUInt16

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asVariant(x)

An object that converts "x" to the ActiveX Automation type Variant. Ensures that ActiveX Automation variants created from "x" are of type VT_VARIANT.

Use

Use this function when passing a VEE data container to an ActiveX control or server that requires a parameter of type VT_VARIANT.

Returns a VEE Variant data type. If the result from this function is assigned to a record field or an array element, its VT_VARIANT nature is lost. See following examples.

Allowed Input Type Return Type

UInt8 | Variant
UInt16 | Variant
Int16 | Variant
Int32 | Variant
Int64 | Variant
Real32 | Variant
Real64 | Variant
Text | Variant

Example

Works:

A = asVariant(A);
Obj.method(ByRef A);

Array = asVariant(Array);

Does Not Work:

Obj.method(ByRef asVariant(A));

Array[0] = asVariant(A);

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asVariant

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asInt64(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asVariantBool(x)

Ensures that ActiveX Automation variants created from "x" are of type VT_BOOL (Boolean).

Use

Use this function when passing a VEE data container to an ActiveX control or server that requires a parameter of type VT_BOOL.

Returns a VEE Int16 data type, with a "hint" flag on the data container that it wants to be a Variant Bool. If this container is passed to an ActiveX Automation Server or Control, it will be translated as VT_BOOL instead of VT_I2. This "hint" flag is only needed if the ActiveX Automation method requires a parameter of type VT_BOOL or ByRef VT_BOOL.

If the result from this function is assigned to a record field or an array element, its VT_BOOL nature is lost. See following examples.

Examples

Works:

A = asVariantBool(A);
Obj.method(ByRef A);

Array = asVariantBool(Array);

Does Not Work:

Obj.method(ByRef asVariantBool(A));

Array[0] = asVariantBool(A);

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asVariantBool

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asVariantCurrency(x)

Ensures that ActiveX Automation variants created from "x" are of type VT_CY (Currency).

Use

Use this function when passing a VEE data container to an ActiveX control or server that requires a parameter of type VT_CY.

Returns a VEE Real64 data type, with a "hint" flag on the data container that it wants to be a Variant Currency. If this container is passed to an ActiveX Automation Server or Control, it will be translated as VT_CY. This "hint" flag is only needed if the ActiveX Automation method requires a parameter of type VT_CY or ByRef VT_CY.

If the result from this function is assigned to a record field or an array element, its VT_CY nature is lost. See following examples.

Examples

Works:

A = asVariantCurrency(A);
Obj.method(ByRef A);

Array = asVariantCurrency(Array);

Does Not Work:

Obj.method(ByRef asVariantCurrency(A));

Array[0] = asVariantCurrency(A);

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asVariantCurrency

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asVariantDate(x)

Ensures that ActiveX Automation variants created from "x" are of type VT_DATE.

Use

Use this function when passing a VEE data container to an ActiveX control or server that requires a parameter of type VT_DATE.

Returns a VEE Real64 data type, with a "hint" flag on the data container that it wants to be a Variant Date. If this container is passed to an ActiveX Automation Server or Control, it will be translated as VT_DATE. This "hint" flag is only needed if the ActiveX Automation method requires a parameter of type VT_DATE or ByRef VT_DATE.

If the result from this function is assigned to a record field or an array element, its VT_DATE nature is lost. See following examples.

Examples

Works:

A = asVariantDate(A);
Obj.method(ByRef A);

Array = asVariantDate(Array);

Does Not Work:

Obj.method(ByRef asVariantDate(A));

Array[0] = asVariantDate(A);

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asVariantDate

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantEmpty(x), asVariantError(x), asVariantNull(x).


asVariantEmpty(x)

Ensures that ActiveX Automation variants created from "x" are of type VT_EMPTY.

Use

Use this function when passing a parameter to an ActiveX control or server, and you want the parameter to be interpreted as VT_EMPTY.

Can only be used on scalars. Not valid for use with a ByRef parameter. Returns the same data type, with a "hint" flag on the data container that it wants to be a Variant Empty. If this container is passed to an ActiveX Automation Server or Control, it will be translated as VT_EMPTY instead of the container's true data type. This "hint" flag is only needed if the ActiveX Automation method requires a parameter of type VT_EMPTY.

If the result from this function is assigned to a record field or an array element, its VT_EMPTY nature is lost.

Example

A = asVariantEmpty(A);
Obj.method(A);

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asVariantEmpty

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantError(x), asVariantNull(x).


asVariantError(x)

Ensures that ActiveX Automation variants created from "x" are of type VT_ERROR.

Use

Use this function when passing a VEE data container to an ActiveX control or server that requires a parameter of type VT_ERROR.

Returns a VEE Int32 data type, with a "hint" flag on the data container that it wants to be a Variant Error. If this container is passed to an ActiveX Automation Server or Control, it will be translated as VT_ERROR. This "hint" flag is only needed if the ActiveX Automation method requires a parameter of type VT_ERROR or ByRef VT_ERROR. The return value represents the error number (scode).

If the result from this function is assigned to a record field or an array element, its VT_ERROR nature is lost. See following examples.

Examples

Works:

A = asVariantError(A);
Obj.method(ByRef A);

Array = asVariantError(Array);

Does Not Work:

Obj.method(ByRef asVariantError(A));

Array[0] = asVariantError(A);

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asVariantError

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantNull(x).


asVariantNull(x)

Ensures that ActiveX Automation variants created from "x" are of type VT_NULL.

Use

Use this function when passing a parameter to an ActiveX control or server, and you want the parameter to be interpreted as VT_NULL.

Can only be used on scalars. Not valid for use with a ByRef parameter. Returns the same data type, with a "hint" flag on the data container that it wants to be a Variant Null. If this container is passed to an ActiveX Automation Server or Control, it will be translated as VT_NULL instead of the container's true data type. This "hint" flag is only needed if the ActiveX Automation method requires a parameter of type VT_NULL.

If the result from the function is assigned to a record field or an array element, its VT_NULL nature is lost.

Example

A = asVariantNull(A);
Obj.method(A);

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> asVariantNull

See Also

asComplex(x), asCoord(x), asInt16(x), asInt32(x), asPComplex(x), asReal32(x), asReal64(x), asText(x), asUInt8(x), asVariant(x), asVariantBool(x), asVariantCurrency(x), asVariantDate(x), asVariantEmpty(x), asVariantError(x).


asin(x)

An object that returns the arcsine of x.

Use

Use asin(x) to generate the arcsine of the x data with the result in the range of -PI/2 to +PI/2 for Real values. The return value will be in the current Trig Mode units. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

asin(1) returns 90 with Trig Mode set to Degrees.

asin((1.1752012, @90)) returns (1, @90) with Trig Mode set to Degrees.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> asin

See Also

asinh(x), cos(x), sin(x), tan(x), Trig, and Default Preferences.


asinh(x)

An object that returns the hyperbolic arcsine of x.

Use

Use asinh(x) to generate the hyperbolic arcsine of the x data. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

asinh(0) returns 0.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> asinh

See Also

asin(x), cosh(x), Trig, sinh(x), and tan(x).


Assignment

A formula-type object that allows you to assign values to Local or Global variables, or assign values to part of an array or record.

Use

Use an Assignment object to assign values to Local or Global variables, or to change the value of part of an array or record. The Result output terminal on the Assignment object will contain only the newly assigned value of the Local or Global variable, or it will contain that part of the array or record that changed. For example, when using an Assignment operator such as, a[2]=4, the Result terminal would contain a[2] (which is the value, 4). It would not contain all of a. To get all of a, add an output terminal named, a.

Notes

When you have selected Assignment, the Member pane of the Function & Object Browser tool window will display a variety of Assignment examples. Clicking on one of these examples will bring up a VEE object pre-loaded with that Assignment formula. The example objects include:

a[2,*,5:6,4]=b - An Assignment object to modify part of a complicated array.

a[2]=b - An Assignment object to modify part of an array.

globalA=2*b+3 - An Assignment object to modify a global/variable (to do a Set Variable).

rec.field=b - An Assignment object to modify part of a record.

rec.field[2]=b - An Assignment object to modify part of a field of a record.

rec[2].field=b - An Assignment object to modify part of an array of records.

tmp=a, a=b, b=tmp - An Assignment object to swap values using a local.

tmp=a[2], a[2]=a[3], a[3]=tmp - An Assignment object to swap values in an array, using a local.

Location

Device [image] Function & Object Browser [image]  Operators [image]  Assignment

See Also

Function & Object Browser

To Change Values in an Array

Using Assignment Operations


atan(x)

An object that returns the arctangent of x.

Use

Use atan(x) to generate the arctangent of the x data, with the result in the range of -PI/2 to +PI/2 for Real values. The return value will be in the current Trig Mode units. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

atan(1) returns 45 with Trig Mode set to Degrees.

atan((1.5574, @0)) returns (0.999, @0) with Trig Mode set to Radians.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> atan

See Also

atanh(x), atan2(y,x), cos(x), sin(x), tan(x), Trig, and Default Preferences.


atan2(y,x)

An object that returns the arctangent of y divided by x.

Use

Use atan2(y,x) to generate the arctangent of y divided by x, with the proper sign, in the range of -PI to +PI for Real values. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type, with the same shape as the operands. x and y are assumed to be in the current Trig Mode units. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

atan2(1, -1) returns 135 with Trig Mode set to Degrees.

atan2((1, 1), (5, 5)) returns (0.19739, 0) with Trig Mode set to Radians.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> atan2

See Also

atan(x), cos(x), sin(x), tan(x), Trig, and Default Preferences.


atanh(x)

An object that returns the hyperbolic arctangent of x.

Use

Use atanh(x) to generate the hyperbolic arctangent of the x data. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

atanh(0.5) returns 0.5493.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> atanh

See Also

atan(x), cosh(x), sinh(x), and tanh(x).


bartlet(x)

An object used to apply a Bartlet window to a time series of values.

Use

Use bartlet(x) to filter the values in x in the same manner as convolving x with the spectral transform of the Bartlet function. This has the effect of suppressing some of the noise due to the tails of the input sequence and the potential discontinuities they represent when sampling periodic signals.

The input x must be an Array 1D.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Spectrum | Spectrum

If x is a Spectrum, it is first converted to a Waveform using an ifft(x) before the window is applied. The result of the window is then converted back to type Spectrum using an fft(x).

Example

bartlet([1, 1, 1, 1, 1, 1, 1, 1]) returns
[0.125, 0.375, 0.625, 0.875, 0.875, 0.625, 0.375, 0.125].

Notes

The Bartlet function in the time domain is represented as 2*(n+0.5)/N, where n is the position (index) in the array, and N is the size of the array. The result will be an array of the same type as x and will have the same mappings as x (if any).

For a discussion of sidelobe levels and coherent gains, see: Ziemer, Tranter, and Fannin, Signals and Systems, Macmillan Publishing, New York, NY, 1983. ISBN #0-02-431650-4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> bartlet

See Also

blackman(x), convolve(a,b), fft(x), hamming(x), hanning(x), ifft(x), and rect(x).


baseName(str)

An object that returns the file name portion of a file path string.

Use

Use baseName() to isolate the file name found at the end of a directory/file path.

For example, if pathStr is:

c:\Program Files\Agilent\VEE Pro 8.0\examples\apps\chaos.vee

then baseName(pathStr) returns chaos.vee.

Both forward slash ( / ) and backslash ( \ ) are treated as delimiter characters after directory (folder) names. If the entire pathStr contains only one name, that name is considered a file name.

Notes

The baseName() object is simply a Formula object initialized with one input and containing the baseName() equation. You may also type baseName() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

> Built-in Functions
> System Information
> baseName

See Also

dirName(), Formula


Bessel

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Bessel to calculate the bessel function of input data.

i0(x)

i1(x)

j0(x)

j1(x)

jn(x,n)

k0(x)

k1(x)

y0(x)

y1(x)

yn(x,n)

Ai(x)

Bi(x)

Location

Device [image] Function & Object Browser [image] Built-in Functions [image]  Bessel

See Also

i0(x), i1(x), j0(x), j1(x), jn(x,n), k0(x), k1(x), y0(x), y1(x), yn(x,n), Ai(x), and Bi(x).


beta(x,y)

An object used to calculate the beta function of the input (x,y).

Use

Use beta(x,y) to calculate the beta function on x. The beta function is defined as the:

( gamma(x) * gamma(y) ) / gamma(x+y)

The x and y values must be positive.

The x input may be of any shape and size. The second y parameter must be of the same type or be able to be converted to the same type as the x input value. If both of the inputs are arrays, they must be of exactly the same shape and size. The same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

beta(3, 1) returns 0.333333333333333.

beta(8, 7) returns 4.16250416250416E-05.

beta(-1, 3) returns an error.

Notes

If both of the inputs are mapped, then the mappings must be the same. The return value has the same mappings as the input if either input is mapped. If neither of the inputs is mapped, then the output is unmapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> beta

See Also

comb(n,r), factorial(n), gamma(x), and perm(n,r).


Bi(x)

An object used to calculate the B-Airy fractional order Bessel function of the second kind of x.

Use

Use Bi(x) to find the Fractional order Bessel function B-Airy of the second kind of x.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

For Coord input types, the operation is done on the dependent variable.

Example

Bi(1) returns 1.20742359495287.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> Bi

See Also

Ai(x), j0(x), j1(x), jn(x,n), y0(x), y1(x), and yn(x,n).


binomial(a,b)

An object used to calculate the number of combinations of a things taken b at a time.

Use

Use binomial(a,b) to calculate the number of combinations of a things taken b at a time using the formula:

binomial(a, b) = a!/((a-b)! * b!)

The ! symbol means factorial.

a can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

The second b parameter must be of the same type or be able to be converted to the same type as the a input value. If both of the inputs are arrays, they must be of exactly the same shape and size.

The binomial(a,b) operation is only defined for integer operands so the input numbers, while of unique type, are converted to Int32 type before the calculation is done.

Example

binomial(10,3) will return 120 as given by the formula:

10!/((10-3)!*3!) = 10!/(7!*3!) =(10*9*8)/(3*2*1) = 120.

binomial(10.4,3.9) will return 210 as given by the formula:

10!/((10-4)!*4!) = 10!/(6!*4!) = (10*9*8*7)/(4*3*2*1) = 210.

The rule about converting a real to Int32 forces 10.4 to 10 and 3.9 to 4.

Notes

a and b must both be positive and a must be greater than b.

This function is identical to comb(n,r).

If both of the inputs are mapped then the mappings must be the same. The return value has the same mappings as the input if either input is mapped. If neither of the inputs is mapped, then the output is unmapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> binomial

See Also

beta(x,y), comb(n,r), factorial(n), gamma(x), and perm(n,r).


bit(x,n)

An object that returns the binary value in a particular bit position.

Use

Use bit(x,n) to return the bit value in the nth position of x, with a value of zero or one. If x is of type Real32, Real64, Coord or Waveform, it is converted to Int32 before the operation. n must be a container that is, or can be converted to, Int32 and has a value between 0 and 31 inclusive (between 0 and 63 inclusive when x is of type Int64). n must be either scalar or match the shape of x. x can be any shape and the same shape is returned.

Allowed Input Type |  | Return Type
x | n
UInt8 | 0-31 | UInt8
UInt16 |  | UInt16
Int16 |  | Int16
Int32 |  | Int32
Int64 | 0-63 | Int64
Real32 | 0-31 | Int32
Real64 |  | Int32
Coord |  | Int32
Waveform |  | Int32

Example

bit(9,0) returns 1 because the binary value of 9 is 1001 and the 0 bit is set.

Notes

The return value has the same mappings as x. Mappings on n are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> bit

See Also

bits(str), Bitwise, clearBit(x,n), and setBit(x,n).


bitAnd(x,y)

An object that returns the Bitwise AND of x and y.

Use

Use bitAnd(x,y) to perform a binary AND on two containers. x and y can be any shape. But if both are arrays, the shape and sizes must match. If x or y are of type Real32, Real64, Coord or Waveform, they are converted to Int32 before the operation. Note that their type orders do not change while their types change. See here for more information on data type order.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

Example

bitAnd(5, [3, 12]) returns [1, 4].

Notes

If any of the input parameters are mapped, then those mappings must be the same. The resultant container retains the mappings of the input container. If only one of the inputs is mapped, the resultant container has those mappings.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> bitAnd

See Also

a AND b, bit(x,n), bitCmpl(x), bitOr(x,y), Bitwise, bitXor(x,y), NOT a, a OR b, and a XOR b.


bitCmpl(x)

An object that returns the Bitwise 1's complement of x.

Use

Use bitCmpl(x) to perform a binary 1's complement on a container. If x is of type Real32, Real64, Coord or Waveform, it is converted to Int32 before the operation. x may be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Int32
Real64 | Int32
Coord | Int32
Waveform | Int32

Example

bitCmpl(7) returns -8.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> bitCmpl

See Also

a AND b, bit(x,n), bitAnd(x,y), bitOr(x,y), Bitwise, bitXor(x,y), NOT a, a OR b, and a XOR b.


bitOr(x,y)

An object that returns the Bitwise OR of x and y.

Use

Use bitOr(x,y) to perform a binary OR on two containers. x and y can be any shape. But if both are arrays, the shapes and sizes must match. If x or y are of type Real32, Real64, Coord or Waveform, they are converted to Int32 before the operation. Note that their type orders do not change while their types change. See here for more information on data type order.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

Example

bitOr(5, [3, 12]) returns [7, 13].

Notes

If any of the input parameters are mapped, then those mappings must be the same. The resultant container retains the mappings of the input container. If only one of the inputs is mapped, the resultant container has those mappings.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> bitOr

See Also

a AND b, bit(x,n), bitAnd(x,y), bitCmpl(x), Bitwise, bitXor(x,y), NOT a, a OR b, and a XOR b.


bits(str)

An object that returns the binary value of a string of 0s and 1s.

Use

Use bits(str) to return an Int32 with the value of the digits in the Text str, converted to Int32 as base 2. str must be a Text container of any shape. str may only contain leading white space, then 0s and 1s to form a binary number.

Example

bits("011") returns 3.

Notes

The return value has the same mappings as the input container. The least significant bit is on the right, and the most significant bit is on the left.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> bits

See Also

bit(x,n), Bitwise, clearBit(x,n), and setBit(x,n).


bitShift(x,y)

An object that returns x with the bits shifted left or right y places.

Use

Use bitShift(x,y) to shift the bits of container x by y places. x may be any shape. If x is of type Real32, Real64, Coord or Waveform, it is converted to Int32 before the operation. y must be a container which is or can be converted to Int32. If y is negative, the bits are shifted right; otherwise the bits are shifted left. y must be either scalar or match the shape of x. If y is greater than 31 or less than -31, the return value will be zero.

Allowed Input Type |  | Return Type
x | y
UInt8 | 0-31 | UInt8
UInt16 |  | UInt16
Int16 |  | Int16
Int32 |  | Int32
Int64 | 0-63 | Int64
Real32 | 0-31 | Int32
Real64 |  | Int32
Coord |  | Int32
Waveform |  | Int32

Example

bitShift([1, 7, 7], [3, 2, (-2)]) returns [8, 28, 1].

bitShift(8,2) returns 32.

bitShift(8,-2) returns 2.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> bitShift

See Also

bit(x,n), bitAnd(x,y),
 bitOr(x,y), Bitwise,
 bitXor(x,y), clearBit(x,n),
 rotate(x, numElem), and setBit(x,n).


Bitwise

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Bitwise to access the following objects which set, clear, access, or shift bits in an UInt8, UInt16, Int16, Int32, or Int64, or perform binary AND, OR, and XORs on UInt8s, UInt16s, Int16s, Int32s,or Int64s.

bit(x,n)

bits(str)

setBit(x,n)

clearBit(x,n)

bitAnd(x,y)

bitOr(x,y)

bitXor(x,y)

bitCmpl(x)

bitShift(x,y)

Notes

The objects on the Bitwise menu make sense only for the types UInt8, UInt16, Int16, Int32, or Int64. But for ease of use, most of the objects accept most types, and will convert the arguments to Int32 before performing the function. This means that the values of Real32s, Real64s, Coords, and Waveforms are truncated inside the objects.

Bits are numbered from zero.

Location

Device [image] Function & Object Browser [image] Built-in Functions [image]  Bitwise

See Also

bit(x,n), bits(str), bitAnd(x,y), bitCmpl(x),
 bitOr(x,y), bitShift(x,y),
 bitXor(x,y), clearBit(x,n),
 setBit(x,n), a AND b, NOT a, a OR b, Comparison,
 and a XOR b.


bitXor(x,y)

An object that returns the Bitwise XOR of x and y.

Use

Use bitXor(x,y) to perform a binary XOR (exclusive or) on two containers. x and y can be any shape. But if both are arrays, the shapes and sizes must match. If x or y are of type Real32, Real64, Coord, or Waveform, they are converted to Int32 before the operation. Note that their type orders do not change while their types change. See here for more information on data type order.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

Example

bitXor(5, [3, 12]) returns [6, 9].

Notes

If any of the input parameters are mapped, then those mappings must be the same. The resultant container retains the mappings of the input container. If only one of the inputs is mapped, the resultant container has those mappings.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> bitXor

See Also

a AND b, bit(x,n), bitAnd(x,y), bitCmpl(x), bitOr(x,y), Bitwise, NOT a, a OR b, and a XOR b.


blackman(x)

An object used to apply a Blackman window to a time series of values.

Use

Use blackman(x) to filter the values in x in the same manner as convolving x with the spectral transform of the Blackman function. This has the effect of suppressing some of the noise due to the tails of the input sequence and the potential discontinuities they represent when sampling periodic signals.

The input x must be an Array 1D.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Spectrum | Spectrum

If x is a Spectrum, it is first converted to a Waveform using an ifft(x) before the window is applied. The result of the window is then converted back to type Spectrum using an fft(x).

Example

blackman([1, 1, 1, 1, 1, 1, 1, 1]) returns
[0.014, 0.172, 0.555, 0.938, 0.938, 0.555, 0.172, 0.014].

Notes

The Blackman function is represented in the time domain as:

0.42 - 0.5*cos(2*PI*(n+0.5)/N) + 0.08*cos(4*PI*(n+0.5)/N)

where n is the position (index) in the array, and N is the size of the array. The result will be an array of the same type as x and will have the same mappings as x (if any).

For a discussion of sidelobe levels and coherent gains, see: Ziemer, Tranter, and Fannin, Signals and Systems, Macmillan Publishing, New York, NY, 1983. ISBN #0-02-431650-4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> blackman

See Also

bartlet(x), convolve(a,b), fft(x), hamming(x), hanning(x), ifft(x), and rect(x).


buildRecord()

buildRecord(fieldNameTextArray, field1, field2, fieldN)

An object that builds a record by specifying the field names and field values at runtime.

Use

Use buildRecord() to build a record whose field names and values are not known until runtime. The first parameter is an array of strings for the field names. The following parameters are values for each field, and the number of these parameters must match that array length.

buildRecord() returns a Scalar Record with the specified field names and field values.

Example

buildRecord(fieldNameList2Long, field1, field2);

builldRecord(fieldNameList8Long, field1, field2, field3... field8);

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> buildRecord

See Also

Build Record


Calculus

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Calculus to take the integral or the derivative of a one-dimensional array of simple numeric values (integer, real, Waveform, ...) or lists of two-dimensional (two field) coordinates.

integral(x)

deriv(x,1)

deriv(x,2)

deriv(x,order)

defIntegral(x,a,b)

derivAt(x,1,pt)

derivAt(x,2,pt)

derivAt(x,order,pt)

Notes

The integral and derivative functions are applicable to one-dimensional arrays of simple numeric values (integer, real, Waveform, and so forth) and lists of two-dimensional (two field) coordinates which represent equally spaced ordered data. For unmapped arrays, it is assumed that the data is equally spaced and ordered, and a value of 1 is assumed for the interval dx between points. For mapped arrays, the operation is performed with the interval value dx equal to (Xmax-Xmin)/N and is thus automatically scaled appropriately. For a coordinate list, the independent (first field) values are first checked to be sure that they are ordered and equally spaced, then the operation is performed on the dependent (second field) values using the previously determined spacing as the value for dx.

If an unmapped array is used, but it is known otherwise that the interval between points is some value dx, then the correct value for the operation can still be obtained. For the integral, multiply the result by the known dx value. For the derivative, divide the result by the known dx value.

Location

Device [image] Function & Object Browser [image] Built-in Functions [image] Calculus

See Also

defIntegral (x,a,b), deriv(x, order), derivAt(x, order,pt), and integral(x).


ceil(x)

An object that returns the rounded-up value of x to the nearest integer of a container.

Use

The ceil(x) function returns the smallest integer (as the same type) greater than or equal to x; that is, the value of x rounded to the next larger integer, the nearest integer towards positive infinity.

x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

ceil([23.0, 23.1, 23.9, 23.5, (-23.5)]) returns [23, 24, 24, 24, -23].

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Real Parts
> ceil

See Also

abs(x), Complex Parts, floor(x), fracPart(x), intPart(x), Real Parts, and round(x).


charToInt(a)

An object that converts the first character of the input string into its decimal value.

Use

Use charToInt(a) to convert the first character of the ASCII input string a into its decimal value of type Int32. The allowed characters are those convertible to values within the range 0 through 255.

Examples

charToInt("A") returns 65.

charToInt("Arthur") also returns 65.

charToInt("a") returns 97.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> charToInt

See Also

intToChar(a), and String.


clearBit(x,n)

An object that returns x with the nth bit set to 0.

Use

Use clearBit(x,n) to set a particular binary digit of a container x to 0. x can be any shape. If x is of type Real32, Real64, Coord or Waveform, it is converted to Int32 before the operation. n must be a container which is, or can be converted to, Int32 and has a value between 0 and 31 inclusive ( between 0 and 63 inclusive when x is of type Int64). n must be either scalar or match the shape of x.

Allowed Input Type |  | Return Type
x | n
UInt8 | 0-31 | UInt8
UInt16 |  | UInt16
Int16 |  | Int16
Int32 |  | Int32
Int64 | 0-63 | Int64
Real32 | 0-31 | Int32
Real64 |  | Int32
Coord |  | Int32
Waveform |  | Int32

Example

clearBit(7,1) returns 5 because the binary value of 7 is 111, and the first bit is cleared yielding 101 (decimal 5). (Bit numbering starts with 0.)

Notes

The mappings of the resultant container are the same as the x parameter.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> clearBit

See Also

bits(str), bit(x,n), Bitwise, and setBit(x,n).


clipLower (x,a)

An object used to clip the input data x to a certain minimum value a.

Use

Use clipLower(x,a) to clip the data to a minimum value a, that is, any data that is less than a will be changed to a.

The x input may be of any size and shape. The clip parameter a must be of the same type, or be able to be converted to the same type, as the x input value and must either be Scalar in shape or the same shape and size as x. If one of the inputs is Scalar and one of the inputs is non-Scalar, the Scalar input is treated as if it were an array of the same shape and size as the non-Scalar input.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform
Text | Text

Example

Using the clipLower(x,.5) function on data, where x is the array [.1, .4, .6, .9], returns [.5, .5, .6, .9].

Using clipLower([.1, .4, .6, .9],[.2, .2, .7, .7]) returns [.2, .4, .7, .9].

You can use clipLower to clip the values of a Waveform to an arbitrary lower limit. Use an array of Coords to define the limiting points on the waveform. The limiting points are the endpoints of line segments that define the limiting waveform shape. There might be just a few of these points. Send the Coord array through the Build Arb Waveform object to create a lower limit waveform with the same number of points as your actual waveform. Send that new waveform into a clipLower function as the a input. When the clipLower(x,a) is done, the input waveform x will have all values below the lower limit clipped to the minimum allowed by the a input.

Notes

If both of the inputs are mapped, then the mappings must be the same. The return value has the same mappings as the input if either input is mapped. If neither of the inputs is mapped, then the output is unmapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> clipLower

See Also

clipUpper (x,a), Build Arb Waveform, and Comparator.


clipUpper (x,a)

An object used to clip the input data x to a certain maximum value a.

Use

Use clipUpper(x,a) to clip the data to a maximum value a. That is, any data that is greater than a will be changed to a.

The x input may be of any size and shape. The clip parameter a must be of the same type, or be able to be converted to the same type, as the x input value and must either be Scalar in shape or the same shape and size as x. If one of the inputs is Scalar and one of the inputs is non-Scalar, the Scalar input is treated as if it were an array of the same shape and size as the non-Scalar input.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform
Text | Text

Example

Using the clipUpper(x,.5) function on data, where x is the array [.1, .4, .6, .9], returns [.1, .4, .5, .5].

Using clipUpper([.1, .4, .6, .9],[.2, .2, .5, .5]) returns [.1, .2, .5, .5].

You can use clipUpper to clip the values of a waveform to an arbitrary upper limit. Use an array of Coords to define the limiting points on the waveform. The limiting points are the endpoints of line segments that define the limiting waveform shape. Send the Coord array through the Build Arb Waveform object to create an upper limit waveform with the same amount of points as your actual waveform. Send that new waveform into a clipUpper function as the a input. When the clipUpper(x,a) is done, the input waveform x will have all values above the upper limit clipped to the maximum allowed by the a input.

Notes

If both of the inputs are mapped then the mappings must be the same. The return value has the same mappings as the input if either input is mapped. If neither of the inputs is mapped, then the output is unmapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> clipUpper

See Also

clipLower (x,a), Build Arb Waveform, and Comparator.


cofactor(x, row,col)

An object used to calculate the cofactor of the input matrix x, at row r and column c.

Use

Use cofactor(x,row,col) to calculate the cofactor of the square matrix x. The cofactor of a matrix is defined as the determinant of the submatrix of the input matrix x obtained by deleting the rth row and cth column, times (-1) raised to the (r+c) power.

The x input must be a square matrix shape. The input for the row and column to delete, r and c, must be an Int32 Scalar or be able to be converted to Int32 type.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Complex | Complex, Scalar in shape
PComplex | PComplex, Scalar in shape

A square matrix has the same number of rows as columns.

Example

cofactor(a,1,2), where a is a matrix [ [3, -1, 2], [4, 5, 6], [7, 1, 2] ], returns 34.

Notes

Mappings on the operand are ignored.

The r and c inputs are expected to be of Int32 type or be able to be converted to that type. The rows and columns of the matrix are numbered from 0 to n-1. Therefore, be careful when specifying which row and column to use.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Matrix
> cofactor

See Also

det(x) and minor(x,row, col).


comb(n,r)

An object used to calculate the number of combinations of n things taken r at a time.

Use

Use comb(n,r) to calculate the number of combinations of n things taken r at a time using the formula:

comb(n, r) = n!/((n -r)! * r!)

The ! symbol means factorial.

The n input may be of any shape and size. The second r parameter must be of the same type or be able to be converted to the same type as the n input value. If both of the inputs are arrays, they must be of exactly the same shape and size.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

The comb(n, r) operation is only defined for integer operands so the input numbers, while of unique type, are converted to Int32 type before the calculation is done.

Example

comb(10,3) will return 120 as given by the formula:

10!/((10-3)!*3!) = 10!/(7!*3!) = (10*9*8)/(3*2*1) = 120

comb(10.4,3.9) will return 210 as given by the formula:

10!/((10-4)!*4!) = 10!/(6!*4!) = (10*9*8*7)/(4*3*2*1) = 210

The rule about converting a real to Int32 forces 10.4 to 10 and 3.9 to 4.

Notes

Both n and r must be positive and n must be greater than r.

If both of the inputs are mapped, then the mappings must be the same. The return value has the same mappings as the input if either input is mapped. If neither of the inputs is mapped, then the output is unmapped.

This function is identical to binomial(a,b).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> comb

See Also

beta(x,y), binomial(a,b), factorial(n), gamma(x), and perm(n,r).


Comma Operator

The "," (comma) can be used in expressions as a dyadic operator. When the "," is used to separate two expressions, the left-hand expression is evaluated, but the result is discarded. The result of the right-hand expression is returned.

Use

Use the comma operator in a Formula object with the following syntax:

expression , expression

The "," ensures that the left-hand expression will be evaluated first, but the result will be discarded. Then the result of the right-hand expression is returned.

Example

UserFunc(A),A calls the function named UserFunc, discards the result, and then returns the value of A.

Location

Must be used within a Formula object or other object that takes an expression.

See Also

Triadic Operator.


commandLine()

An object that returns the command-line parameters used to initiate this VEE session.

Use

The return value is a 1D Text array. Index 0 of the array contains the VEE program name that was used to start the VEE session. Subsequent array elements (if any) are the parameters that followed the program name on the command line.

This function is useful when you want to use the VEE command line to pass parameters (options) to your VEE program. Options intended for the VEE environment itself are preceded by a single minus sign ( - ) on the command line. See To Start Agilent VEE with Command-Line Options. Options preceded by two minus signs are ignored by the VEE environment and are made available to the VEE program using the commandLine() object. For example:

vee85.exe -maximize --radians My_Trig.vee

This command line starts VEE with a maximized window, loads the program My_Trig.vee, and lets that program to use the --radians option.

Notes

The commandLine() object is simply a Formula object initialized without inputs and containing the commandLine() equation. You may also type commandLine() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> System Information
> commandLine

See Also

installDir, programName, Formula


Comparison

A Category of Operators on the Function & Object Browser tool window.

Use

Use Comparison to access the following objects which perform comparison operations on two operands:

a ~= b

a == b

a != b

a < b

a > b

a <= b

a >= b

Notes

All of these operations return a scalar Int32 with the value of 0 or 1, which corresponds to whether the operation is true or false.

It is possible for two operands to not be comparable, that is, the two operands are not less than, greater than, or equal to each other. Examples are Coords with mismatched mappings and arrays. For example, [1, 2, 6] != [2, 3, 4] is true, but the two operands are neither less than nor greater than each other, they are simply not equal. That is, [1, 2, 6] < [2, 3, 4] is false, and [1, 2, 6] > [2, 3, 4] is false because each element in the first array is not < or > respectively to each element in the second array.

Also note the difference between items under Comparison and under the menu item Conditional. Comparisons are formulas which output 0 or 1. Conditionals are If/Then/Else and have two outputs, of which one activates.

Note that the return value is of type Int32 and is the same shape as the operands. This is different than the conditionals such as == that always return a scalar.

The logical operators are defined for type Text only in the sense of whether the string is null or not. That is, "zoo" AND "" (null string) is logically false since the second string is null. Remember that when comparing a Text type to a non-string type, the latter is promoted to a Text type. This means that "zoo" AND 0 is true since the real 0 is promoted to the string "0" and, since both strings are non-null, the AND expression is true, returning 1.

Location

Device [image] Function & Object Browser [image] Operators [image]  Comparison

See Also

a ~= b (almost equal to), a AND b, a == b (equal to), a > b (greater than), a >= b (greater than or equal to), a < b (less than), a <= b (less than or equal to), NOT a, a != b (not equal to), a OR b, and a XOR b.

Comparator, Conditional, and If/Then/Else.


Complex Parts

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Complex Parts to access the following objects which return different parts of Complex and PComplex containers.

j(x)

re(x)

im(x)

mag(x)

phase(x)

conj(x)

Notes

The objects on the Complex Parts menu make sense only for the type Complex and PComplex. But for ease of use, most of the objects accept and return most types.

Location

Device [image] Function & Object Browser [image]  Built-in Functions [image] Complex Parts

See Also

conj(x), im(x), j(x), mag(x), phase(x), re(x), and Real Parts.

Build Complex, Build PComplex, Complex, UnBuild Complex, and UnBuild PComplex.


concat(x,y)

An object used to concatenate containers.

Use

Use concat(x,y) to concatenate two containers. The input parameters can be of any type and any shape. The concat(x,y) function will flatten arrays that are greater than one dimension into an Array 1D. The resulting 1D arrays are then concatenated together. For x and y input of all types, a 1D container of the highest type is returned.

Example

If x is a real Scalar container with 3 in it, and y is a Text array container with ["This", "is", "a", "test"] in it, then concat(x,y) will return a Text array container ["3", "This", "is", "a", "test"]. In this case, the numeric 3 has been converted to the higher type Text string "3" before the concat operation.

Notes

If the x value is mapped, the y value may be either mapped with the same point spacing, or unmapped. The result will be mapped from Xmin to Xmin+dx*N, where Xmin is the minimum value of the x mapping, dx is the distance between two consecutive points in x, and N is the size of the resultant array.

Note the difference between the concat(x,y) and sum(x) functions on Text inputs. The concat(x,y) creates an Array 1D in all cases. The sum(x) function will simply link all the text strings together to form one large output string. That is, concat(x,y), where x is the Scalar Text value "a" and y is the Scalar Text input "b", yields the Array 1D ["a","b"]. On the other hand, sum(["a","b"]) will return the Scalar container with the text value of "ab" in it.

All nil inputs are automatically converted to Real64 scalars with the value 0. Thus, where x is nil and y is an Int32 scalar value 5, concat(x,y) results in the Array 1D two long of Real64 with values [0, 5]. In contrast, the Concatenator object with two inputs with nil and an Int32 scalar value 5 will output an Int32 array one long with value [5].

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Array
> concat

See Also

sum(x), and Concatenator.


conj(x)

An object that returns the complex conjugate of a Complex number x.

Use

Use conj(x) to generate the complex conjugate of a Complex number x. x can be any shape and of type Complex, PComplex, or Spectrum. The complex conjugate of a Complex number simply reverses the sign of the imaginary component. The complex conjugate of a PComplex number simply reverses the sign of the phase.

Example

conj( (2, 3) ) returns (2, -3).

conj( (8, @45) ) returns (8, @-45) with Trig Mode set to Degrees.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Complex Parts
> conj

See Also

im(x), j(x), mag(x), phase(x), re(x), Real Parts, Build Complex, Default Preferences, and UnBuild Complex.


convolve(a,b)

An object used to convolve two arrays of data.

Use

Use convolve(a,b) to calculate the discrete aperiodic convolution of two 1D arrays a and b. The result will be an array of the same type and of size (Na+Nb)-1, where Na is the size of input array a, and Nb is the size of input array b.

The input values a and b must be an Array 1D. a and b do not have to be the same size. The resultant values are not normalized.

Allowed Input Types Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Highest type of inputs
Waveform | Highest type of inputs

Example

convolve([1, 2, 3, 4, 5],[1, 1, 1]) returns [1, 3, 6, 9, 12, 9, 5].

Notes

The inputs a and b must represent equally spaced data. In addition, the interval between any two values of a must be the same as that between any two values of b. For two unmapped arrays, it is assumed that the interval is always 1. For mapped arrays, the interval is (Xmax-Xmin)/N, where Xmax and Xmin are the mappings, and N is the size of the array. When one input is mapped and the other is not, the unmapped input is assumed to be sampled at the same frequency as the mapped input. The resultant values will never be normalized to any scale factor.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> convolve

See Also

fft(x) and xcorrelate (a,b).


cos(x)

An object that returns the cosine of x.

Use

Use cos(x) to generate the cosine of the x data. x is assumed to be in the current Trig Mode units. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

cos([0, 180]) returns [1, -1] with Trig Mode set to Degrees.

cos((1, PI/4)) returns (0.715684, -0.73096) with Trig Mode set to Radians.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

> Built-in Functions
> Trig
> cos

See Also

acos(x), cosh(x), sin(x), tan(x), Trig, and Default Preferences.


cosh(x)

An object that returns the hyperbolic cosine of x.

Use

Use cosh(x) to generate the hyperbolic cosine of the x data. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

cosh(0) returns 1.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

> Built-in Functions
> Trig
> cosh

See Also

acosh(x), cos(x), sinh(x), and tanh(x).


cot(x)

An object that returns the cotangent of x.

Use

Use cot(x) to generate the cotangent of the x data. x is assumed to be in the current Trig Mode units. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

cot([45, 90]) returns [1, 61E-18] with Trig Mode set to Degrees. Note that the second number, which should be zero, is smaller than the system precision.

cot((3, @PI/2)) returns (1.0049698, @-1.57079) with Trig Mode set to Radians.

cot((3, @90)) returns (1.0049698, @-90) with Trig Mode set to Degrees.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> cot

See Also

acot(x), atan2(y,x), cos(x), coth(x), sin(x), tan(x), Trig, and Default Preferences.


coth(x)

An object that returns the hyperbolic cotangent of x.

Use

Use coth(x) to generate the hyperbolic cotangent of the x data. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

coth(0.4) returns 2.631.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> coth

See Also

acoth(x), cot(x), sinh(x), and tanh(x).


Create Instance(AssemblyName, ClassName)

Creates a new instance of the .NET object specified by AssemblyName and ClassName, and returns a reference to it. You may specify additional parameters for invoking a particular constructor of the object.

Use

Use CreateInstance to create a .NET object in your program. You should never have a need to write the CreateInstance formula yourself. Instead, open the Function & Object Browser, select the assembly, the namespace, the class type, the appropriate constructor, and use the Create Instance button to create the formula template. This is the best way to save you some typing and avoid mistakes.

The AssemblyName is the name of an assembly that you have already referenced through the .NET assembly reference dialog box. The ClassName is the name of a class qualified with its namespace.

CreateInstance takes any number of additional parameters for invoking a particular constructor of the object. Again, use the Function & Object Browser to select and create the formula template.

Example

This example creates an instance of System.Collections.Hashtable class and returns a reference to it.

Set hashtable = CreateInstance("mscorlib", "System.Collections.Hashtable");

Notes

VEE must be set to VEE 5 (or higher) execution mode for .NET support (Default Preferences).

The assembly reference for a .NET type must be made available to VEE before you can create expressions which use that .NET type (Device [image] .NET Assembly References…).

You will notice that not all .NET types listed in Function & Object Browser have constructors. This is normal. For types without constructors listed, you do not need to call CreateInstance to access the .NET object.

Also, to invoke the static members of a .NET type (those with the [image] icon), you do not need to call CreateInstance first. For example, to invoke the static property Now of System.DateTime, you do not need to construct an object instance first.

Location

Device [image] Function & Object Browser

> Built-in Functions

> .NET Automation

> CreateInstance

See Also

See example programs in the .NET example directories

.NET Example Programs


CreateObject(ProgID)

Creates a new instance of the ActiveX Automation object specified by ProgID and returns a reference to it.

Releasing ActiveX References

Use

Use CreateObject to create an automation object in your program. You will need to modify the initial expression to perform the desired action. Most of the time, you want to create a new instance of an automation object in a new instance of a server application that VEE will control.

The ProgID of an object is a name (human-readable string) assigned by the person who wrote the automation object. It is typically a library or application name, a period, and a component or object name. To find the valid ProgIDs for any ActiveX Automation Server, consult the documentation supplied with that server.

CreateObject takes an optional second parameter that specifies the name of a remote host computer (server) on which to instantiate the object. This functionality requires DCOM to be installed on both the client and the server computers. The syntax is:

createObject( ProgID [, hostName ] )

where:

hostName must be of type Text, and can be specified as either a valid UNC or DNS domain name. Some examples of valid hostName specifications:

Set obj = createObject("lib.obj",
 "server")
Set obj = createObject("lib.obj", "\\\\server")
Set obj = createObject("lib.obj", "server.domain.com")
Set obj = createObject("lib.obj", "135.5.33.19")

Example

This example starts a new instance of Microsoft Excel (even if Excel is already running), and returns a reference to a new Worksheet object:

SET excel = CreateObject ("Excel.Sheet")

Releasing ActiveX References

If your VEE program uses an Automation Server (like Excel), you may notice that the Excel (or whatever) application does not always quit when your program ends. VEE releases all ActiveX references when it exits or when you do a File [image] New operation. If you also want ActiveX references to be released at program completion, there are some programming actions you must take. The following are required to assure that an instantiated Automation Server exits when its object is deleted or the VEE program finishes.

Select Disable Debug Features in Default Preferences. With debugging enabled, VEE retains data and pointer references for use with Line Probe. (You need to decide which is more important to you: debugging and line probing, or releasing ActiveX servers at program completion.)

Delete all declared and undeclared VEE variables before the program completes. Hint: Select All Variables in the Delete Variable object.

If you made any changes to the Excel spreadsheet, Excel wants to ask, "Do you want to save changes?". Even if VEE has released all its references to Excel, Excel still wants a response from somebody before it will exit in a case like this. One way to avoid this situation is to call the Quit() method in Excel.

An alternative technique is to put all your ActiveX functions into a separate VEE library. Then use Import Library to load these functions and Delete Library to release all the ActiveX references when they are no longer needed. For example, you write all your Excel operations as VEE UserFunctions and store them in a library file named “ExcelFuncs.vee.” When the main program wants to access an Excel spreadsheet, it does an Import Library of ExcelFuncs.vee, calls the appropriate UserFunctions to manipulate and store the spreadsheet, then does a Delete Library of ExcelFuncs.vee. At this point, all the references to the Excel Automation Server are removed, and Excel quits.

This alternative involves the extra work of creating and managing a separate library of UserFunctions. However, it allows you to quit Excel programmatically with debugging and line probing enabled. As mentioned above, you still need to save spreadsheet changes or call Excel’s Quit() before calling Delete Library.

Notes

VEE must be set to VEE 5 (or higher) execution mode for ActiveX support (Default Preferences).

The type library for an ActiveX application must be made available to VEE before you can create expressions which control that application (Device [image] ActiveX Automation References…).

VEE does not provide any programmatic control over the security settings used to instantiate objects on remote computers. This can be accomplished statically via the dcomcnfg.exe program that is part of DCOM.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> ActiveX Automation
> CreateObject

See Also

See example programs in the ActiveX example directories
Help [image] Open Example…

ActiveX Automation References, Default Preferences, GetObject.


cubert(x)

An object that returns the cube root of the value of x.

Use

Use cubert(x) to generate the cube root of a number x. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

For PComplex, the cubert(x) is defined as the cube root of the magnitude and one third the phase. Complex is converted to PComplex before the function is applied.

Example

cubert( (8, @90) ) will return (2, @30).

cubert( (1,1) ) will return (1.08, 0.291).

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> cubert

See Also

a ^ b (exponent), Power, sq(x), and sqrt(x).


Data Filtering

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Data Filtering to apply filtering algorithms to the data to smooth it.

polySmooth(x)

meanSmooth(x,numPts)

movingAvg(x,numPts)

clipUpper(x,a)

clipLower(x,a)

minIndex(x)

maxIndex(x)

minX(x)

maxX(x)

Location

Device [image] Function & Object Browser [image]  Built-in Functions [image]  Data Filtering

See Also

polySmooth (x), meanSmooth (x,numPts), movingAvg (x,numPts), clipUpper (x,a), clipLower (x,a), minIndex(x), maxIndex(x), minX(x), maxX(x), Regression, and Signal Processing.


defIntegral (x,a,b)

An object used to calculate the integral of those values of the input data which are between points a and b (inclusive) using Simpson's 1/3 rule.

Use

Use defIntegral(x,a,b) to calculate the numerical approximation of the integral of a set of ordered, equally-spaced values (x) between points a and b.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Waveform | Real64

Example

defIntegral([ 0, 1, 2, 3, 4, 4, 3, 2, 1, 0 ], 2, 5) returns 10.12.

Notes

The defIntegral(x,a,b) function is applicable to one-dimensional arrays of simple numeric values and lists of two-dimensional (two field) coordinates which represent equally spaced ordered data. For unmapped arrays, the values a and b represent indices in the array (0 to N-1). For coordinate lists, the values a and b represent real values between the x-values of the first and last point in the coordinate list (inclusive). For mapped arrays, the values a and b represent real values between the Xmin mapping and Xmax-dx (inclusive), where dx is the interval between consecutive points: (Xmax-Xmin)/N.

For unmapped arrays, it is assumed that the data is equally spaced and ordered, and a value of 1 is assumed for the interval dx between points. For mapped arrays, the operation is performed with the interval value dx equal to (Xmax-Xmin)/N and is thus automatically scaled appropriately. For a coordinate list, the independent (first field) values are first checked to be sure that they are ordered and equally spaced, then the operation is performed on the dependent (second field) values using the previously determined spacing as the value for dx.

If an unmapped array is used, but it is known otherwise that the interval between points is some value dx, then the correct value for the operation can be obtained by multiplying the result of defIntegral(x,a,b) by the known dx value.

When the values represent noisy data, the result of defIntegral(x) can often be improved (in a pragmatic sense) by first filtering or smoothing the data. Smoothing removes much of the unwanted noise which is superimposed on the underlying values. See the polySmooth(x) function and related smoothing functions for examples.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Calculus
> defIntegral

See Also

integral(x).


deriv(x, order)

An object used to calculate the derivative of order order across all values of the input data using a sliding fourth-order (five-point) polynomial.

Use

Use deriv(x,order) to calculate the numerical approximation of the derivative of order order across all points of a set of ordered equally spaced values (x). The result is an array of the same size and shape as the input x.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Waveform | Real64

Example

deriv([0, 1, 2, 3, 3, 2, 1, 0], 1) returns
[1.25, 0.9167, 1.083, 0.5833, -0.5833, -1.083, -0.9167, -1.25].

Notes

The deriv(x,order) function is applicable to one-dimensional arrays of simple numeric values and lists of two-dimensional (two field) coordinates that represent equally spaced ordered data. For mapped arrays, the mappings of the resultant array will be identical to those of x. For coordinate lists, the values a and b represent real values between the x-values of the first and last point in the coordinate list (inclusive). For mapped arrays, the values a and b represent real values between the Xmin mapping and Xmax-dx (inclusive), where dx is the interval between consecutive points: (Xmax-Xmin)/N.

For unmapped arrays, it is assumed that the data is equally spaced and ordered, and a value of 1 is assumed for the interval dx between points. For mapped arrays, the operation is performed with the interval value dx equal to (Xmax-Xmin)/N and is thus automatically scaled appropriately. For a coordinate list, the independent (first field) values are first checked to be sure that they are ordered and equally spaced, then the operation is performed on the dependent (second field) values using the previously determined spacing as the value for dx.

If an unmapped array is used, but it is known otherwise that the interval between points is some value dx, then the correct value for the operation can be obtained by dividing the result of deriv(x,order) by the known dx value.

When the values represent noisy data, the result of deriv(x,order) can often be improved (in a pragmatic sense) by first filtering or smoothing the data. Smoothing removes much of the unwanted noise which is superimposed on the underlying values. See the polySmooth(x) function and related smoothing functions for examples.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Calculus
> deriv

See Also

derivAt(x, order,pt).


derivAt(x, order,pt)

An object used to calculate the derivative of order order at value pt of the input data using a sliding fourth-order (five-point) polynomial.

Use

Use derivAt(x,order,pt) to calculate the numerical approximation of the derivative of order order at some point pt in the set of ordered equally spaced values (x).

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Real64

Example

derivAt([ 0, 1, 2, 3, 3, 2, 1, 0 ], 1, 3) returns 0.5833.

Notes

The derivAt(x,order,pt) function is applicable to one-dimensional arrays of simple numeric values (integer, real, Waveform) and lists of two-dimensional (two field) coordinates that represent equally spaced ordered data. For unmapped arrays, the value a represents an index in the array (0 to N-1). For coordinate lists, the values a and b represent real values between the x-values of the first and last point in the coordinate list (inclusive). For mapped arrays, the values a and b represent real values between the Xmin mapping and Xmax-dx (inclusive), where dx is the interval between consecutive points: (Xmax-Xmin)/N.

For unmapped arrays, it is assumed that the data is equally spaced and ordered, and a value of 1 is assumed for the interval dx between points. For mapped arrays, the operation is performed with the interval value dx equal to (Xmax-Xmin)/N and is thus automatically scaled appropriately. For a coordinate list, the independent (first field) values are first checked to be sure that they are ordered and equally spaced. Then the operation is performed on the dependent (second field) values using the previously determined spacing as the value for dx.

If an unmapped array is used, but it is known otherwise that the interval between points is some value dx, then the correct value for the operation can be obtained by dividing the result of derivAt(x,order,pt) by the known dx value.

When the values represent noisy data, the result of derivAt(x,order,pt) can often be improved (in a pragmatic sense) by first filtering or smoothing the data. Smoothing removes much of the unwanted noise which is superimposed on the underlying values. See the polySmooth(x) function and related smoothing functions for examples.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Calculus
> derivAt

See Also

deriv(x, order).


det(x)

An object used to calculate the determinant of a square matrix.

Use

Use det(x) to calculate the determinant of the square matrix x. The x input must be a square matrix shape. A square matrix has the same number of rows as columns.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Complex | Complex, Scalar in shape
PComplex | PComplex, Scalar in shape

Example

Where x is a square matrix [ [1, 2], [3, 4] ], det(x) returns -2.

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Matrix
> det

See Also

identity(x), inverse(x), and transpose(x).


dirName()

dirName(str)

An object that returns the directory portion of file path string.

Use

Use dirName() to isolate the directory information found at the front of a directory/file path.

For example, if pathStr is:

c:\Program Files\Agilent\VEE\examples\apps\chaos.vee

then dirName(pathStr) returns:

c:\Program Files\Agilent\VEE\examples\apps

Both forward slash ( / ) and backslash ( \ ) are treated as delimiter characters after directory (folder) names. If the entire pathStr contains only one name, that name is considered a file name. In those cases, dirName() returns the null string.

Notes

The dirName() object is simply a Formula object initialized with one input and containing the dirName() function. You may also type dirName() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

> Built-in Functions
> System Information
> dirName

See Also

baseName(), Formula


a div b (truncated division)

An object that performs an arithmetic div (truncated division) on two operands.

Use

Use a div b to determine the number of times one container divides evenly into another container, that is, the truncated division value. The two containers may be of any shape. But if one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type, with the same shape as the operands.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. The div is only performed on the dependent (last) variable.

Example

A scalar div an array: 3.2 DIV [1, 2, 3, 4] returns [3, 1, 1, 0].

An array div a scalar: [1, 2, 3] DIV 2 returns [0, 1, 1].

Two scalars: 12.95 DIV 4 returns 3.

Two Coord scalars: coord(1,3) DIV coord(1,5) returns coord(1,0).

Two Coord scalars: coord(1,3) DIV coord(2,5) returns an error.

Notes

If either of the containers is mapped (that is, of type Waveform, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Arithmetic
> DIV

See Also

a + b (add), a / b (divide), a * b (multiply), and a - b (subtract).


a / b (divide)

An object that performs an arithmetic division of two operands.

Use

Use a / b to divide the value of one container by the value of another container. The two containers may be of any shape. However, if one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type, with the same shape as the operands.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

PComplex

Spectrum

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. The division is only performed on the dependent (last) variable.

This division operation performs a parallel division on all arrays, including matrices. For a matrix divide, see the function matDivide(numer,denom).

Example

A scalar divided by an array: 3.0 / [1, 2, 3] returns [3, 1.5, 1].

Two arrays: [4, 5, 6] / [1, 2, 3] returns [4, 2.5, 2].

Two PComplex scalars: (1,@90) / (2,@30) returns (0.5, @60) with Trig Mode set to Degrees.

Two Coord scalars: coord(1,3) / coord(1,5) returns coord(1,0.6).

Two Coord scalars: coord(1,3) / coord(2,5) returns an error.

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Arithmetic
> /

See Also

a + b (add), a div b (truncated division), matDivide (numer, denom), a * b (multiply), and a - b (subtract).


dmyToDate (d,m,y)

An object that returns the value of the parameters d, m, and y converted to a date.

Use

Use dmyToDate(d,m,y) to convert three values, day, month, and year, into the date. d, m, and y can be any shape. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type, with the same shape as the operands.

Allowed Input Types Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

dmyToDate(25, 12, 1991) returns 62.8293999G.

Notes

If any of the input parameters are mapped, then those mappings must be the same. The resultant container retains the mappings of the input container. If only one of the inputs is mapped, the resultant container has those mappings.

Also note that dmy is specified as modern Gregorian dates.

The value of d (the day) must be in the range 1 through 31.

The value of m (the month) must be in the range 1 through 12.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> dmyToDate

See Also

hmsToHour (h,m,s), hmsToSec (h,m,s), mday(aDate), month(aDate), now(), Time & Date, wday(aDate), and year(aDate).


a == b (equal to)

An object that performs an is equal to operation on two operands.

Use

Use a == b to determine whether the value(s) of one container is equal to the value(s) of another container. The two containers may be of any type and of any shape. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a scalar Int32 with the value 0 or 1. If the first operand is equal to the second, the value of the result is 1; otherwise the value is 0.

If both operands are of type Coord, they must have all their independent variable(s) and dependent variables match exactly for the result to be 1. If independent variables do not match, an error is returned. Complex, PComplex, and Spectrum containers must have both parts match for the operation to return 1. Enums are converted to Text for the comparison.

Arrays must have all the respective values of both containers equal for the operation to return 1.

If both operands are of type Boolean, the result is a Boolean of the same shape as the operands.

Example

Two Boolean scalars: True == False returns False.

A scalar and an array: 3.0 == [3, 3, 3] returns 1.

A scalar and an array: 3.0 == [3, 1, 3] returns 0.

Two arrays: [1, 2, 3] == [1, 2, 4] returns 0.

Two PComplex scalars: (1,@90) == (1,@85) returns 0.

Two Complex scalars: (2,3) == (2,4) returns 0.

Two Complex scalars: (2,3) == (2,3) returns 1.

Two Coord scalars: coord(1,3) == coord(1,5) returns 0.

Two Coord scalars: coord(1,3) == coord(2,3) returns an error: Values for independent variables must match.

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Comparison
> ==

See Also

a ~= b (almost equal to), a AND b, a > b (greater than), a >= b (greater than or equal to), a < b (less than), a <= b (less than or equal to), NOT a, a != b (not equal to), a OR b, Comparison, a XOR b, Comparator, Conditional, and If/Then/Else.


erf(x)

An object used to calculate the error function of the input x.

Use

Use erf(x) to calculate the error function of x. The erf function is defined as:

(2/SQRT(PI) ) * [ the integral of ( e^(-t^2)) * dt ]

where the integral is evaluated over the range from zero to x. The x input may be of any shape and size.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

erf(.5) returns 0.52049987781305.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> erf

See Also

erfc(x).


erfc(x)

An object used to calculate the complementary error function of the input x.

Use

Use erfc(x) to calculate the complementary error function of x. The erfc function is defined as:

1-(2/SQRT(PI)) * [the integral of ( e^(-t^2)) * dt]

where the integral is evaluated over the range from zero to x. The x input may be of any shape and size.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

erfc(.5) returns 0.47950012218695.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

The erfc(x) function, which returns 1.0 - erf(x), is provided because of the extreme loss of relative accuracy if a large x is called for in erf(x), the result is subtracted from 1.0 (for example, x=5, twelve places are lost).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> erfc

See Also

erf(x).


errorInfo()

An object that provides information about the last error trapped on an error output pin.

Use

Use errorInfo() to determine error information for the last error trapped when using error output pins. After the error is trapped, execute an errorInfo() object to create a record that contains all the information that would be displayed in an error dialog box. The record contains the following fields:

Field Name Data Type Description

Number Int32 scalar The error number

Message Text scalar The error message text associated with this error

More Text 1D array Any extra information associated with this error

Title Text scalar The title of the object that generated the error

Type Text scalar The type of the object that generated the error

Notes

The errorInfo() object is simply a Formula object initialized without inputs and containing the errorInfo() equation. You may also type errorInfo() into any other Formula object or expression.

If no error was output to an error output pin, the record created by ErrorInfo contains no data.

errorInfo() only traps run-time errors, not pre-run errors such as when an input terminal is not connected.

errorInfo() does not give information about entrapped errors (which generate an error message dialog box).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> System Information
> errorInfo

See Also

Error Output (Object Menu), Formula, and Raise Error.


exp(x)

An object that returns the exponential of the value of x.

Use

Use exp(x) to generate the exponential, or natural antilogarithm (base e), of a number x; that is, e raised to the x power. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

exp(10) returns 22.0264657948k.

exp((1,2)) returns (-1.131204384, 2.471726672).

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> exp

See Also

exp10(x), a ^ b (exponent), log(x), log10(x), and Power.


exp10(x)

An object that returns the exponential base 10 of the value of x.

Use

Use exp10(x) to generate the common antilogarithm (base 10) of a number x; that is, 10 raised to the x power. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

exp10(10) returns 10G.

exp10((1, 2)) returns (-4.16146837, 9.09297427).

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> exp10

See Also

exp(x), a ^ b (exponent), log(x), log10(x), and Power.


a ^ b (exponent)

An object that performs an arithmetic exponentiation of two operands.

Use

Use a ^ b to raise one number to the power of the other number. The two containers may be of any shape. But if one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type, with the same shape as the operands.

Allowed Input Types Return Type

UInt8 | the highest type of the two operands *
UInt16
Int16
Int32
Int64
Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

* For example, if the number is uint8 and the power is int32, the return type is int32. This would still be true if the two types were reversed.

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. The exponentiation is only performed on the dependent (last) variable.

Example

A scalar raised to an array: 3.0 ^ [1, 2, 3] returns [3, 9, 27].

An array raised to a scalar: [1, 2, 3] ^ 3 returns [1, 8, 27].

Two arrays: [4, 5, 6] ^ [1, 2, 3] returns [4, 25, 216].

Two Complex scalars: (2,3) ^ (4,5) returns (-0.753046, -0.986429).

Two Coord scalars: coord(4,3) ^ coord(4,2) returns coord(4,9).

Two Coord scalars: coord(1,3) ^ coord(2,5) returns an error.

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

There was a change in behavior from VEE 4 to VEE 5. In VEE 4, the power is assumed to be of type real regardless of how the number is presented, ie. -1 is real number -1.0. In VEE 5, the power is assumed to be an integer. If the power is presented as 1., then it is recognized as real.

Location

Device [image] Function & Object Browser

>  Operators
> Arithmetic
> ^

See Also

exp(x) and log(x).


Exponential Regression

An object used to fit an exponential curve to (x,y) data.

Use

Use the exponential regression to fit the data to the equation y = C0 + exp(C1*x), where x is the x coordinate and C0 and C1 are calculated coefficients. The exp function is the transcendental number e raised to the (C1*x) power.

The exponential regression object expects an array of Coord type of input with one independent variable, that is, an (x,y) pair. If the input array is not a Coord type, an attempt is made to convert it to Coord. If the input data is mapped (Waveform, Spectrum, or a mapped array) then the conversion to Coord uses the mapping information to create the x part of the (x,y) pairs. If the input data is not mapped (for example, an array), then the x part of the (x,y) pair is implicitly generated from its position in the array.

Open View Parameters

The Fit Type field on the open view is used to change the regression type to linear, logarithmic, exponential, power curve or polynomial regression. Clicking on the field will bring up a list of the different regression types.

Example

See Regression for a Coord conversion example.

Notes

See Regression for general notes on regression.

Location

Device [image] Regression

then select the appropriate Fit Type from the Fit Type field on the dialog box.

See Also

Regression, linear regression, logarithmic regression, meanSmooth (x,numPts), movingAvg (x,numPts), polynomial regression, polySmooth (x), power curve regression and Build Coord.


factorial(n)

An object used to calculate the factorial of the input number n.

Use

Use factorial(n) to calculate the factorial of the natural number n. The factorial is defined for any natural number n as n! = (n) * (n-1) * (n-2) . . . (3) * (2) * (1).

The n input may be of any shape and size. The n input must not be less than zero.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

The factorial(n) operation is only defined for integer operands so the input numbers, while of unique type, are converted to Int32 type before the calculation is done.

Example

factorial(6) returns 720 from the multiplication of 6*5*4*3*2*1.

factorial(6.7) returns 5040 from the multiplication of 7*6*5*4*3*2*1. The rule about converting a real to Int32 forces 6.7 to 7.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> factorial

See Also

beta(x,y), binomial(a,b),
 comb(n,r), gamma(x), and
 perm(n,r).


fft(x)

An object to compute the Discrete Fourier Transform on the input data.

Use

Use fft(x) to calculate the Discrete Fourier Transform of the values in x. The result represents the positive half of the transformed values. The size of the resultant array will be (N DIV 2)+1, where N is the size of the input array.

Allowed Input Type Return Type

UInt8 | Complex Array
UInt16 | Complex Array
Int16 | Complex Array
Int32 | Complex Array
Int64 | Complex Array
Real32 | Complex Array
Real64 | Complex Array
Waveform | Waveform

The input x must represent an array of ordered, equally-spaced data. For non-Waveform inputs, the output will be an unmapped array of Complex values. For Waveform inputs, the output will be mapped from a minimum frequency of 0 to a maximum frequency of (1+(N DIV 2))/(Tmax-Tmin), where N is the size of the input array, and Tmin and Tmax are the mappings of the input Waveform. Also note that the output will not be normalized.

Example

fft([0, 1, 2, 3, 4, 5, 6, 7])

returns [(28,0), (-4,9.657), (-4,4), (-4,1.657), (-4,0)]

Notes

Truncation and Periodicity: A basic assumption in the use of the discrete Fourier transform is that the given waveform h(t) is periodic. If this is not the case, then the waveform must be truncated and represented as a periodic function. For a band-limited periodic function h(t), the waveform must be truncated at an integer multiple of the period; otherwise, the resulting discrete and continuous Fourier transform will differ considerably in that sidelobes, frequency leakage, and sharp discontinuities can appear. These difficulties are often reduced through the use of windows. If the waveform is not band-limited, one generally must adjust (increase) the truncation interval and use windows [0,L] to reduce time-domain truncation errors. L is defined as the period of the waveform.

Aliasing: The problem of aliasing (frequency folding) occurs when the sampling interval T is too large. One can expect a degradation in the performance of the discrete Fourier transform when the sampling rate is close to the Nyquist sampling rate. If the waveform is not periodic or not band-limited, increasing the truncation interval[0,L] and decreasing the sampling interval T can help to control truncation errors and aliasing.

A reference on the fft can be found in the book: E. Oran Brigham, The Fast Fourier Transform and Its Applications, Second Edition, Prentice-Hall, Inc., Englewood Cliffs, NJ, 1988. ISBN #0-13-307505-2.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> fft

See Also

convolve(a,b) and ifft(x).


floor(x)

An object that returns the rounded-down value of x to the nearest integer of a value.

Use

x may be any shape. The floor(x) function returns the largest integer (as the same type) less than or equal to x; that is, the value of x rounded to the next smaller integer, the integer nearest negative infinity.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

floor([23.0, 23.1, 23.9, 23.5, (-23.5)]) returns [23, 23, 23, 23, -24].

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Real Parts
> floor

See Also

abs(x), ceil(x), Complex Parts, fracPart(x), intPart(x), Real Parts, and round(x).


fracPart(x)

An object that returns the value of the fractional part of x.

Use

Use fracPart(x) to obtain the fractional part of a container. x may be any shape. The fracPart(x) function returns the fractional part of x with the same sign. It returns x - intPart(x).

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

fracPart([23.0, 23.1, 23.9, 23.5, (-23.5)]) returns
0, 0.1, 0.9, 0.5, -0.5].

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Real Parts
> fracPart

See Also

abs(x), ceil(x), Complex Parts, floor(x), intPart(x), Real Parts, and round(x).


Freq Distribution

Part of the Built-in Functions in the Category of Probability & Statistics on the Function & Object Browser tool window.

Use

Use the Freq Distribution functions to calculate the distribution of values over a range into a fixed number of sub-ranges. The Name of these functions are:

magDist(x,from,thru,step)

logMagDist(x,from,thru,logStep)

Location

Device [image] Function & Object Browser [image]  Built-in Functions [image]  Probability & Statistics

See Also

Function & Object Browser, logMagDist (x,from,thru, logStep), and magDist(x, from,thru, step).


gamma(x)

An object used to calculate the gamma function of the input x.

Use

Use gamma(x) to calculate the gamma function of x. The gamma function is defined as:

(the integral of [ t^(x-1) * e^(-t) * dt ])

where the integral is evaluated over the range from 0 to infinity. The x input may be of any shape.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Examples

gamma(8) returns (8-1)! = 5040.

gamma(-1) returns an error.

gamma(3.7) returns = 4.17065178379660.

gamma(-3.7) returns = 0.251643995902422.

Notes

The gamma(x) function is not defined for non-positive integral values of x. When x is a positive integer, gamma(x) is defined as (x-1)! (factorial).

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> gamma

See Also

beta(x,y), comb(n,r), factorial(n), and perm(n,r).


Generate

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Generate to access the following objects which generate Real64 one-dimensional arrays of data with specific values.

ramp(numElem,from,thru)

logRamp(numElem,from,thru)

xramp(numElem,from,thru)

xlogRamp(numElem,from,thru)

Location

Device [image] Function & Object Browser [image]  Built-in Functions [image]  Generate

See Also

logRamp (numElem, from,thru), ramp (numElem, from,thru), xlogRamp (numElem, from,thru), and xramp (numElem, from,thru).


getEnv(envStr)

Part of the VEE system information Built-in Functions that allow you to access environment variables.

Use

You can use getEnv to access the values of environment variables in VEE. When you select this function, the getEnv(envStr) object will appear. The (envStr) represents a string (Text object) that identifies the name of the environment variable you are looking for. Enter the string name of the environment variable you are looking for, inside the parentheses.

When the getEnv(envStr) object executes, it will return the value of the environment variable that was specified by the string as a Text object.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> System Information
> getEnv

See Also

errorInfo(), getHostname(),
 installDir(), whichOS(),
 and whichVersion()


getHostname()

Part of the VEE system information Built-in Functions that allow you to determine the name of the host computer on which VEE is running.

Use

You can use getHostname() to find out the name of the host computer on which your VEE program is running. When you select the getHostname function, the getHostname() object will appear. The object does not require any parameters, but when the object is executed, it will return the name of the host computer.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> System Information
> getHostname

See Also

errorInfo(), getEnv(envStr),
 installDir(), whichOS(),
 and whichVersion().


GetObject

GetObject(fileName, ProgID)

Loads the ActiveX Automation object saved in fileName, using the object specified by ProgID and returns a reference to it.

Use

Use GetObject to get an ActiveX automation object that already exists in a running application, or to load an existing object from a file. An object already exists if it was created by an expression using the CreateObject function, or the object creation occurred outside the scope of the VEE program. You will need to modify the initial expression to perform the desired action.

The ProgID of an object is a name (human-readable string) assigned by the person who wrote the automation object. It is typically a library or application name, a period, and a component or object name. To find the valid ProgIDs for any ActiveX Automation Server, consult the documentation supplied with that server. The ProgID parameter is optional. If ProgID is omitted, VEE uses the Component Object Model (COM) library to determine what application is associated with the file.

Examples

The following example returns a reference to a currently running Microsoft Excel application’s Application object. Excel must be running or this expression will cause an error:

SET excel = GetObject ("","Excel.Application")

The next example loads an existing object from a file. It returns a reference to the Sheet object associated with d:\tmp\TestData.xls in the currently running Excel application. If Excel is not running, it will start before loading the object.

SET excel = GetObject ("d:\\tmp\\TestData.xls","Excel.Sheet")

Notes

VEE must be set to VEE5 or higher execution mode for ActiveX support (Default Preferences).

The automation type library for an application must be made available to VEE before you can create expressions which control that application (Device [image] ActiveX Automation References…).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> ActiveX Automation
> GetObject

See Also

See example programs in the ActiveX example directories
Help [image] Open Example…

ActiveX Automation References, Default Preferences, CreateObject.


a > b (greater than)

An object that performs an is greater than operation on two operands.

Use

Use a > b to determine whether the value(s) of one container is greater than the value(s) of another container. The two containers may be of any shape.

Allowed Input Type Return Type

UInt8 | Int32
UInt16 | Int32
Int16 | Int32
Int32 | Int32
Int64 | Int32
Real32 | Int32
Real64 | Int32
Coord | Int32
Waveform | Int32
Text | Int32
Enum | Int32

If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a scalar Int32, with the value 0 or 1. If the first operand is greater than the second, the value of the result is 1; otherwise the value is 0.

If both operands are of type Coord, their independent variable(s) must be identical before the operation is even attempted; if not, an error is returned. Enums are converted to Text for the comparison. Text is compared using ASCII lexical ordering.

When two arrays are compared to each other, each pair of elements must satisfy the relational operator for the operation to return 1.

Example

A scalar and an array: 3.0 > [1, 3, 9] returns 0.

An array and a scalar: [5, 9, 7] > 4 returns 1.

Two arrays: [3, 4, 7] > [2, 3, 5] returns 1.

Two arrays: [3, 4, 3] > [2, 3, 5] returns 0.

Two Coord scalars: coord(1,3) > coord(1,5) returns 0.

Two Coord scalars: coord(1,3) > coord(2,5) returns Values for independent variables must match.

Two Text scalars: "too" > "zoo" returns 0.

Notes

If either of the containers is mapped (that is, of type Waveform, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Comparison
> >

See Also

a ~= b (almost equal to), a AND b, a == b (equal to), a >= b (greater than or equal to), a < b (less than), a <= b (less than or equal to), NOT a, a != b (not equal to), a OR b, Comparison, a XOR b, Comparator, Conditional, and If/Then/Else.


a >= b (greater than or equal to)

An object that performs an is greater than or equal to operation on two operands.

Use

Use a >= b to determine whether the value(s) of one container is greater than or equal to the value(s) of another container. The two containers may be of any shape.

Allowed Input Type Return Type

UInt8 | Int32
UInt16 | Int32
Int16 | Int32
Int32 | Int32
Int64 | Int32
Real32 | Int32
Real64 | Int32
Coord | Int32
Waveform | Int32
Text | Int32
Enum | Int32

If one of the containers is an array, the other must be either be a scalar or an array of the same size and shape. The result is a scalar Int32, with the value 0 or 1. If the first operand is greater than or equal to the second, the value of the result is 1; otherwise the value is 0.

If both operands are of type Coord, their independent variable(s) must be identical before the operation is even attempted; if not, an error is returned. Enums are converted to Text for the comparison. Text is compared using ASCII lexical ordering.

When two arrays are mapped against each other, each set of elements must satisfy the relational operator for the operation to return 1.

Example

A scalar and an array: 3.0 >= [1, 3, 9] returns 0.

An array and a scalar: [4, 5, 6] >= 4 returns 1.

Two arrays: [3, 3, 6] >= [2, 3, 5] returns 1.

Two arrays: [1, 4, 3] >= [2, 3, 5] returns 0.

Two Coord scalars: coord(1,3) >= coord(1,5) returns 0.

Two Coord scalars: coord(1,3) >= coord(2,5) returns Values for independent variables must match.

Two Text scalars: "too" >= "zoo" returns 0.

Notes

If either of the containers is mapped (that is, of type Waveform, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Comparison
> >=

See Also

a ~= b (almost equal to), a AND b, a == b (equal to), a > b (greater than), a < b (less than), a <= b (less than or equal to), NOT a, a != b (not equal to), a OR b, Comparison, a XOR b, Comparator, Conditional, and If/Then/Else.


hamming(x)

An object used to apply a Hamming window to a time series of values.

Use

Use hamming(x) to filter the values in x in the same manner as convolving x with the spectral transform of the Hamming function. This has the effect of suppressing some of the noise due to the tails of the input sequence and the potential discontinuities they represent when sampling periodic signals.

The input x must be an Array 1D.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Spectrum | Spectrum

If x is a Spectrum, it is first converted to a Waveform using an ifft(x) before the window is applied. The result of the window is then converted back to type Spectrum using an fft(x).

Example

hamming([1, 1, 1, 1, 1, 1, 1, 1]) returns
[0.115, 0.364, 0.716, 0.965, 0.965, 0.716, 0.364, 0.115].

Notes

The Hamming function is represented in the time domain as

0.54-0.46*cos(2*PI*(n+0.5)/N)

where n is the position (index) in the array, and N is the size of the array. The result will be an array of the same type as x and will have the same mappings as x (if any).

For a discussion of sidelobe levels and coherent gains, see: Ziemer, Tranter, and Fannin, Signals and Systems, Macmillan Publishing, New York, NY, 1983. ISBN #0-02-431650-4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> hamming

See Also

bartlet(x), blackman(x), convolve(a,b), fft(x), hanning(x), ifft(x), and rect(x).


hanning(x)

An object used to apply a Hanning window to a time series of values.

Use

Use hanning(x) to filter the values in x in the same manner as convolving x with the spectral transform of the Hanning function. This has the effect of suppressing some of the noise due to the tails of the input sequence and the potential discontinuities they represent when sampling periodic signals.

The input x must be an Array 1D.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Spectrum | Spectrum

If x is a Spectrum, it is first converted to a Waveform using an ifft(x) before the window is applied. The result of the window is then converted back to type Spectrum using an fft(x).

Example

hanning([1, 1, 1, 1, 1, 1, 1, 1]) returns
[0.038, 0.309, 0.691, 0.962, 0.962, 0.691, 0.309, 0.038].

Notes

The Hanning function is represented in the time domain as

0.5*(1-cos(2*PI*(n+0.5)/N))

where n is the position (index) in the array, and N is the size of the array. The result will be an array of the same type as x and will have the same mappings as x (if any).

For a discussion of sidelobe levels and coherent gains, see: Ziemer, Tranter, and Fannin, Signals and Systems, Macmillan Publishing, New York, NY, 1983. ISBN #0-02-431650-4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> hanning

See Also

bartlet(x), blackman(x), convolve(a,b), fft(x), hamming(x), ifft(x), and rect(x).


help(topic,filename)

Part of the VEE system information Built-in Functions that allow you to link to custom help topics.

Use

You can link to a custom help topic file by using the help object. The syntax is:

help(topic,filename)

topic - The name of the help topic you wish to link to.

filename - The filename that contains the help topic information.

When your VEE program starts, and this object is executed, the help system will open the filename associated with the specified topic.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> System Information
> help

See Also

installDir()


hidePanel()

An object that hides a UserFunction panel displayed with showPanel().

Use

Use hidePanel() to stop displaying a UserFunction panel that was shown with showPanel().

Open View

You must include the text hidePanel(). Inside the parenthesis, you type the following parameter:

"UFname" - The name of the UserFunction. You must have double quotes around this name. This parameter is required.

You may add a data input pin to the hidePanel() object to set the UserFunction name, but you must replace "UFname" with the input terminal name.

Notes

The hidePanel() object is simply a Formula object initialized without inputs and containing the hidePanel("UFname") equation. You may also type hidePanel() (and the associated parameter) into any other Formula object.

You may input the entire hidePanel() equation via control pin.

All panels are hidden once the program stops executing.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Panel
> hidePanel

See Also

Call, lockPosition(),
 showPanel(), panelPosition(),
 panelSize(), unlockPosition(),
 and UserFunction.


hmsToHour (h,m,s)

An object that returns the value of the parameters h, m, and s converted to hours.

Use

Use hmsToHour(h,m,s) to convert three values, hours, minutes, and seconds, into hours. h, m, and s can be any shape. If one of the containers is an array, the others must be either scalar or arrays of the same size and shape. The resulting container has the same shape as the operands.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

hmsToHour(1, [0, 12, 60], 36) returns [1.01, 1.21, 2.01].

Notes

If any of the input parameters are mapped, then those mappings must be the same. The resultant container retains the mappings of the input container. If only one of the inputs is mapped, the resultant container has those mappings.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> hmsToHour

See Also

dmyToDate (d,m,y), hmsToSec (h,m,s), mday(aDate), month(aDate), now(), Time & Date, wday(aDate), and year(aDate).


hmsToSec (h,m,s)

An object that returns the value of the parameters h, m, and s converted to seconds.

Use

Use hmsToSec(h,m,s) to convert three values, hours, minutes, and seconds, into seconds. h, m, and s can be any shape. If one of the containers is an array, the others must be either scalar or arrays of the same size and shape. The resulting container has the same shape as the operands.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

hmsToSec(1,[2, 4, 6],3) returns [3723, 3843, 3963].

Notes

If any of the input parameters are mapped, then those mappings must be the same. The resultant container retains the mappings of the input container. If only one of the inputs is mapped, the resultant container has those mappings.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> hmsToSec

See Also

dmyToDate (d,m,y), hmsToHour (h,m,s), mday(aDate), month(aDate), now(), Time & Date, wday(aDate), and year(aDate).


Hyper Bessel

See the help topic, Bessel.


Hyper Trig

See the help topic, Trig.


i0(x)

An object used to calculate the modified (hyperbolic) Bessel function of x of the first kind of order zero.

Use

Use i0(x) to find the modified (hyperbolic) Bessel function of x of the first kind of order zero. The x input may be of any size and shape. For Coord input types, the operation is done on the dependent variable.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

i0(1) returns 1.26606587775200.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> i0

See Also

i1(x), k0(x), and k1(x).


i1(x)

An object used to calculate the modified (hyperbolic) Bessel function of x of the first kind of order one.

Use

Use i1(x) to find the modified (hyperbolic) Bessel function of x of the first kind of order one. The x input may be of any size and shape. For Coord input types, the operation is done on the dependent variable.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

i1(1) returns 0.565159103992485.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> i1

See Also

i0(x), k0(x), and k1(x).


identity(x)

An object used to return the identity matrix.

Use

Use identity(x) to return the identity matrix that is the same size as the square input matrix. The x input must be a square matrix. A square matrix has the same number of rows as columns.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Complex | Complex
PComplex | PComplex

Example

Where x is a square matrix [ [1, 2], [3, 4] ], identity(x) returns
[ [1, 0], [0, 1] ].

Where x is the complex square matrix [ [(1,1), (2,2)], [(3,3), (4,4)] ], identity(x) returns [ [(1,0), (0,0)], [(0,0), (1,0)] ].

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Matrix
> identity

See Also

det(x), inverse(x), and transpose(x).


ifft(x)

An object to compute the Inverse Discrete Fourier Transform on the input data.

Use

Use ifft(x) to calculate the Inverse Discrete Fourier Transform of the values in x. The input x should be the positive half of a symmetric Complex, PComplex, or Spectral sequence.

Allowed Input Type | Return Type
Complex | Real64
PComplex | Real64
Spectrum | Waveform

The size of the resultant array depends on the information used to create the incoming array. As described for fft(x), an fft done on arrays of 256 and 257 points each results in arrays containing 129 points. The information in each array differs slightly based on the different number of points. Using ifft(x) on these 129-point arrays results in the original 256- and 257-point arrays. For non-Spectrum inputs, the output will be an unmapped array of Real values. For Spectrum inputs, the mapping must be linear (not log), and Fmin must be 0. The output will be mapped from a minimum time of 0 to a maximum time of N/(Fmax-Fmin), where N is the size of the input array, and Fmin and Fmax are the mappings of the input Spectrum. Also note that the output will not be normalized.

It is assumed that the values of x represent data that has not been normalized.

Example

ifft([(3.5,0), (-1,2.414), (-1,1), (-1,0.414), (-1,0)]) returns
[0, 1, 2, 3, 4, 5, 6, 7].

Notes

1. Truncation and Periodicity: A basic assumption in the use of the discrete Fourier transform is that the given waveform h(t) is periodic. If this is not the case, then the waveform must be truncated and represented as a periodic function. For a band-limited periodic function h(t), the waveform must be truncated at an integer multiple of the period; otherwise, the resulting discrete and continuous Fourier transform will differ considerably since sidelobes, frequency leakage, and sharp discontinuities can appear. These difficulties are often reduced through the use of windows. If the waveform is not band-limited, you generally must increase the truncation interval and use windows [0,L] to reduce time-domain truncation errors. L is defined as the period of the waveform.

2. Aliasing: The problem of aliasing (frequency folding) occurs when the sampling interval T is chosen too large. One can expect a degradation in the performance of the discrete Fourier transform when the sampling rate is close to the Nyquist sampling rate. If the waveform is not periodic or not band-limited, increasing the truncation interval [0,L] and decreasing the sampling interval T can help to control truncation errors and aliasing.

A reference on the ifft can be found in the book: E. Oran Brigham, The Fast Fourier Transform and Its Applications, Second Edition, Prentice-Hall, Inc., Englewood Cliffs, NJ, 1988. ISBN #0-13-307505-2.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> ifft

See Also

fft(x).


im(x)

An object that returns the imaginary part of a Complex number x.

Use

Use im(x) to extract the imaginary part of a Complex number x. x can be any shape. (PComplex is first converted to Complex.)

Allowed Input Type Return Type

UInt8 | UInt8, value of zero
UInt16 | UInt16, value of zero
Int16 | Int16, value of zero
Int32 | Int32, value of zero
Int64 | Int64, value of zero
Real32 | Real32, value of zero
Real64 | Real64, value of zero
Coord | Coord, value of zero
Waveform | Waveform, value of zero
Complex | Real64, value of the imaginary part
PComplex | Real64, value of the imaginary part
Spectrum | Real64, value of the imaginary part

Example

im( (1,2) ) returns 2.

im( (1,@90) ), with Trig Mode in Degrees, returns 1.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Complex Parts
> im

See Also

conj(x), j(x), mag(x), phase(x), re(x), Real Parts, Build Complex, and UnBuild Complex.


inDaylightSavings()

An object that indicates if computer time is in Daylight Savings Time.

Use

Use inDaylightSavings() to determine if your computer is in Daylight Savings Time or Standard Time. It returns zero if the current computer time is Standard Time. It returns non-zero if the current computer time is Daylight Savings Time.

Notes

The inDaylightSavings() object is simply a Formula object initialized without inputs and containing the inDaylightSavings() equation. You may also type inDaylightSavings() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> inDaylightSavings

See Also

now, Formula.


init(x,val)

An object used to initialize an array to a specific value.

Use

Use init(x,val) to initialize an input array x to a value of val. The x input may be of any size and shape, and of any type. For all x input types, the same output type is returned (except the Error output, which returns Text). The second val parameter must be of the same type or be able to be converted to the same type as the x input value.

If the input x is an array then the val init value parameter can be a Scalar value or an array. If val is an array, it must have the same number of dimensions and size as the x input. That is, if x is an Array 1D then val can either be a Scalar or an Array 1D of the same size. For Records, the schema of x and val must match.

Example

init(a,5) initializes the input array to a value of 5.

init(a,[1, 2, 3]) initializes an input array of three elements to the values [1, 2, 3].

Notes

The init value must be the same type as the input array or be able to be converted to the same type. That is, you cannot initialize a real array to a complex initial value because a complex number cannot be converted to a real number.

The mapping on the output container is the same as the input val.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Array
> init

See Also

ramp (numElem, from,thru), randomize (x,low,high), and Allocate Array.


installDir()

An object that returns the directory path where Agilent VEE is installed.

Use

You can use installDir() to determine the directory where Agilent VEE is installed on your computer. The path is retrieved from the registry on the PC.

Notes

You can use the command line option -d <dirname> to specify a starting directory different from the install directory. If you use the -d option, installDir() returns the starting directory specified on the command line.

The installDir() object is simply a Formula object initialized without inputs and containing the installDir() equation. You may also type installDir() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> System Information
> installDir

See Also

errorInfo(), getEnv(envStr),
 getHostname(), whichVersion(),
 and commandLine().


integral(x)

An object used to calculate the integral across all values of the input data using Simpson's 1/3 rule.

Use

Use integral(x) to calculate the numerical approximation of the indefinite integral of a set of ordered, equally-spaced values (x).

Allowed Input Type Return Type

UInt8 | Real64 (same mappings, if any)
UInt16 | Real64 (same mappings, if any)
Int16 | Real64 (same mappings, if any)
Int32 | Real64 (same mappings, if any)
Int64 | Real64(same mappings, if any)
Real32 | Real64 (same mappings, if any)
Real64 | Real64 (same mappings, if any)
Coord | Coord
Waveform | Waveform

Example

integral([ 0, 1, 2, 3, 3, 2, 1, 0 ]) returns
[ 0, 0.5, 2, 4.5, 7.667, 10.17, 11.67, 12.17 ].

Notes

The integral(x) function is applicable to one-dimensional arrays of simple numeric values and lists of two-dimensional (two field) coordinates that represent equally spaced ordered data. For mapped arrays, the mappings of the resultant array will be identical to those of x. For coordinate lists, the values of the independent field (first field) of each coordinate will be identical to those of the corresponding values in x.

For unmapped arrays, it is assumed that the data is equally spaced and ordered, and a value of 1 is assumed for the interval dx between points. For mapped arrays, the operation is performed with the interval value dx equal to (Xmax-Xmin)/N and is thus automatically scaled appropriately. For a coordinate list, the independent (first field) values are first checked to be sure that they are ordered and equally spaced, then the operation is performed on the dependent (second field) values using the previously determined spacing as the value for dx.

If an unmapped array is used, but it is known otherwise that the interval between points is some value dx, then the correct value for the operation can be obtained by multiplying the result of integral(x) by the known dx value.

When the values represent noisy data, the result of integral(x) can often be improved (in a pragmatic sense) by first filtering or smoothing the data. Smoothing removes much of the unwanted noise which is superimposed on the underlying values. See the polySmooth(x) function and related smoothing functions for examples.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Calculus
> integral

See Also

defIntegral (x,a,b).


intPart(x)

An object that returns the value of the integer part of x.

Use

Use intPart(x) to obtain the integer part of a container. x may be any shape. The intPart(x) function returns the integer portion of the data. If the data is less than zero, it returns the ceil(x); otherwise it returns the floor(x). The result will have the same mappings as x.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

intPart([23.0, 23.1, 23.9, 23.5,(-23.5)]) returns
[23, 23, 23, 23, -23].

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Real Parts
> intPart

See Also

abs(x), ceil(x), Complex Parts, floor(x), fracPart(x), Real Parts, and round(x).


intToChar(a)

An object that converts the numeric input to an ASCII character.

Use

Use intToChar(a) to convert a numeric input to an ASCII character. The object converts the input to a long integer first, then converts the integer to a character.

Notes

The range of values converted to characters is 0 through 255. The object accommodates inputs outside this range by converting only the low-order byte of a 32-bit integer input. The upper three bytes are ignored.

VEE uses the same TEXT(String) as C and C++, so intToChar(0) is equivalent to NUL or an empty string. NUL is a string terminator. For example, the string 123NUL456 produces the string 123. The remainder of the string, 456, is ignored.

Examples

intToChar(65) returns A.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> IntToChar

See Also

charToInt(a), and String.


inverse(x)

An object used to calculate the inverse of a square matrix.

Use

Use inverse(x) to calculate the inverse of the square matrix x. The x input must be a square matrix shape (the same number of rows as columns).

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Complex | Complex
PComplex | PComplex

Example

Where x is a square matrix [ [1, 2], [3, 4] ], inverse(x) returns
[ [-2, 1], [1.5, -0.5] ].

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Matrix
> inverse

See Also

det(x), identity(x), and transpose(x).


isVariant(x)

Queries "x" to determine if it was created from an ActiveX variant.

Use

If "x" is an array, this function operates on the array container, not on individual array elements. For example, isVariant(A) works properly, but isVariant(A[0]) does not.

ActiveX data can be declared as type Variant, then be assigned data of a specific type. The isVariant function tells you if the variable was declared as a Variant or not. The typeName function tells you the data type currently assigned to the Variant.

Example

someMethod (ByRef x);

isVar = isVariant (x);

The isVar variable now contains a zero or nonzero value, indicating if "x" was truly of type Variant or not.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> isVariant

See Also

isVariantBool(x), isVariantCurrency(x), isVariantDate(x), isVariantEmpty(x), isVariantError(x), isVariantNull(x), typeName(x).


isVariantBool(x)

Queries "x" to determine if it was created from an ActiveX variant of type Boolean.

Use

ActiveX Automation Boolean data types (VT_BOOL) are returned to VEE as Int16 containers with a "hint" that the container is really a VT_BOOL type. The container can be queried to determine if it is truly an Int16 or a Boolean type.

If "x" is an array, this function operates on the array container, not on individual array elements. For example, isVariantBool(A) works properly, but isVariantBool(A[0]) does not. The return value is an Int16, with 0 for false and nonzero for true.

Example

someMethod (ByRef x);

isBool = isVariantBool (x);

The isBool variable now contains a zero or nonzero value, indicating if "x" was truly of type VT_BOOL or not.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> isVariantBool

See Also

isVariant(x), isVariantCurrency(x), isVariantDate(x), isVariantEmpty(x), isVariantError(x), isVariantNull(x), typeName(x).


isVariantCurrency(x)

Queries "x" to determine if it was created from an ActiveX variant of type Currency.

Use

ActiveX Automation Currency data types (VT_CY) are returned to VEE as Real64 containers with a "hint" that the container is really a VT_CY type. The container can be queried to determine if it is truly a Real64 or a Currency type.

If "x" is an array, this function operates on the array container, not on individual array elements. For example, isVariantCurrency(A) works properly, but isVariantCurrency(A[0]) does not. The return value is an Int32, with 0 for false and nonzero for true.

Example

someMethod (ByRef x);

isCurrency = isVariantCurrency (x);

The isCurrency variable now contains a zero or nonzero value, indicating if "x" was truly of type VT_CY or not.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> isVariantCurrency

See Also

isVariant(x), isVariantBool(x), isVariantDate(x), isVariantEmpty(x), isVariantError(x), isVariantNull(x), typeName(x).


isVariantDate(x)

Queries "x" to determine if it was created from an ActiveX variant of type Date.

Use

ActiveX Automation Date data types (VT_DATE) are returned to VEE as Real64 containers with a "hint" that the container is really a VT_DATE type. The container can be queried to determine if it is truly a Real64 or a Date type.

If "x" is an array, this function operates on the array container, not on individual array elements. For example, isVariantDate(A) works properly, but isVariantDate(A[0]) does not. The return value is an Int32, with 0 for false and nonzero for true.

Example

someMethod (ByRef x);

isDate = isVariantDate (x);

The isDate variable now contains a zero or nonzero value, indicating if "x" was truly of type VT_DATE or not.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> isVariantDate

See Also

isVariant(x), isVariantBool(x), isVariantCurrency(x), isVariantEmpty(x), isVariantError(x), isVariantNull(x), typeName(x).


isVariantEmpty(x)

Queries "x" to determine if it was created from an ActiveX variant that is empty.

Use

Use to determine if the returned Variant was Empty (instead of Variant containing an empty string).

If "x" is an array, this function operates on the array container, not on individual array elements. For example, isVariantEmpty(A) works properly, but isVariantEmpty(A[0]) does not. The return value is an Int32, with 0 for false and nonzero for true.

Example

someMethod (x);

isEmpty = isVariantEmpty (x);

The isEmpty variable now contains a zero or nonzero value indicating if "x" was truly an empty Variant or not.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> isVariantEmpty

See Also

isVariant(x), isVariantBool(x), isVariantCurrency(x), isVariantDate(x), isVariantError(x), isVariantNull(x), typeName(x).


isVariantError(x)

Queries "x" to determine if it was created from an ActiveX variant of type Error.

Use

ActiveX Automation Error data types (VT_ERROR) are returned to VEE as Int32 containers with a "hint" that the container is really a VT_ERROR type. The container can be queried to determine if it is truly an Int32 or an Error type. The value represents the error number (scode).

If "x" is an array, this function operates on the array container, not on individual array elements. For example, isVariantError(A) works properly, but isVariantError(A[0]) does not. The return value is an Int32, with 0 for false and nonzero for true.

Example

someMethod (x);

isError = isVariantError (x);

The isError variable now contains a zero or nonzero value indicating if "x" was truly of type VT_ERROR or not.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> isVariantError

See Also

isVariant(x), isVariantBool(x), isVariantCurrency(x), isVariantDate(x), isVariantEmpty(x), isVariantNull(x), typeName(x).


isVariantNull(x)

Queries "x" to determine if it was created from an ActiveX variant that contains a Null.

Use

Use to determine if the returned Variant contained a VT_NULL (instead of the Int32 value of 0).

If "x" is an array, this function operates on the array container, not on individual array elements. For example, isVariantNull(A) works properly, but isVariantNull(A[0]) does not. The return value is an Int32, with 0 for false and nonzero for true.

Example

someMethod (x);

isNull = isVariantNull (x);

The isNull variable now contains a zero or nonzero value indicating if "x" was truly of type VT_NULL or not.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Type Conversion
> isVariantNull

See Also

isVariant(x), isVariantBool(x), isVariantCurrency(x), isVariantDate(x), isVariantEmpty(x), isVariantError(x), typeName(x).


j(x)

An object that returns a Complex number with x as the imaginary part.

Use

Use j(x) to generate a Complex number of the same shape as x, with x as the imaginary part and 0 as the real part. The same shape is returned.

Allowed Input Type Return Type

UInt8 | Complex
UInt16 | Complex
Int16 | Complex
Int32 | Complex
Int64 | Complex
Real32 | Complex
Real64 | Complex
Waveform | Complex

Example

j(5) returns the Complex number (0,5).

Notes

Mappings are retained in the result. To return a complex number with x as the real part, use the type promotions on input terminals to promote real to Complex.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Complex Parts
> j

See Also

Complex Parts, conj(x), im(x), mag(x), phase(x), re(x), Real Parts, Build Complex, and UnBuild Complex.


j0(x)

An object used to calculate the Bessel function of x of the first kind of order zero.

Use

Use j0(x) to find the Bessel function of x of the first kind of order zero. The x input may be of any size and shape. For Coord input types, the operation is done on the dependent variable.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

j0(10) returns -0.245935764451348.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> j0

See Also

Ai(x), Bi(x), j1(x), jn(x,n), y0(x), y1(x), and yn(x,n).


j1(x)

An object used to calculate the Bessel function of x of the first kind of order one.

Use

Use j1(x) to find the Bessel function of x of the first kind of order one. The x input may be of any size and shape. For Coord input types, the operation is done on the dependent variable.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

j1(1) returns 0.440050585744933.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> j1

See Also

Ai(x), Bi(x), j0(x), jn(x,n), y0(x), y1(x), and yn(x,n).


jn(x,n)

An object used to calculate the Bessel function of x of the first kind of order n.

Use

Use jn(x,n) to find the Bessel function of x of the first kind of order n. The x input may be of any size and shape. For Coord input types, the operation is done on the dependent variable.

The n parameter must be of Int32 type or be able to be converted to Int32. It must be Scalar in shape or the same shape as x.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

jn(1,2) returns 0.114903484931900.

Notes

If both of the inputs are mapped, then the mappings must be the same. The return value has the same mappings as the input if either input is mapped. If neither of the inputs is mapped, then the output is unmapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> jn

See Also

Ai(x), Bi(x), j0(x) , j1(x), y0(x), y1(x), and yn(x,n).


k0(x)

An object used to calculate the modified (hyperbolic) Bessel function of x of the second kind of order zero.

Use

Use k0(x) to find the modified (hyperbolic) Bessel function of x of the second kind of order zero. The x input may be of any size and shape. For Coord input types, the operation is done on the dependent variable.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

k0(1) returns 0.421024438240708.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

The x argument must be positive.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> k0

See Also

i0(x), i1(x), and k1(x).


k1(x)

An object used to calculate the modified (hyperbolic) Bessel function of x of the second kind of order one.

Use

Use k1(x) to find the modified (hyperbolic) Bessel function of x of the second kind of order one. The x input may be of any size and shape. For Coord input types, the operation is done on the dependent variable.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

k1(1) returns 0.601907230197234.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

The x argument must be positive.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> k1

See Also

i0(x), i1(x), and k0(x).


a < b (less than)

An object that performs an is less than operation on two operands.

Use

Use a < b to determine whether the value(s) of one container is less than the value(s) of another container. The two containers may be of any shape. But if one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a scalar Int32, with the value 0 or 1. If the first operand is less than the second, the value of the result is 1; otherwise the value is 0.

Allowed Input Type Return Type

UInt8 | Int32
UInt16 | Int32
Int16 | Int32
Int32 | Int32
Int64 | Int32
Real32 | Int32
Real64 | Int32
Coord | Int32
Waveform | Int32
Text | Int32
Enum | Int32

If both operands are of type Coord, their independent variable(s) must be identical before the operation is even attempted; if not, an error is returned. Enums are converted to Text for the comparison. Text is compared using ASCII lexical ordering.

When two arrays are compared to each other, each pair of elements must satisfy the comparison operator for the operation to return 1.

Example

A scalar and an array: 3.0 < [1, 3, 9] returns 0.

An array and a scalar: [1, 2, 3] < 4 returns 1.

Two arrays: [1, 2, 3] < [2, 3, 5] returns 1.

Two arrays: [1, 4, 3] < [2, 3, 5] returns 0.

Two Coord scalars: coord(1,3) < coord(1,5) returns 1.

Two Coord scalars: coord(1,3) < coord(2,5) returns Values for independent variables must match.

Two Text scalars: "too" < "zoo" returns 1.

Notes

If either of the containers is mapped (that is, of type Waveform, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Comparison
> <

See Also

a ~= b (almost equal to), a AND b, a == b (equal to) , a > b (greater than), a >= b (greater than or equal to), a <= b (less than or equal to), NOT a, a != b (not equal to), a OR b, Comparison, a XOR b, Comparator, Conditional, and If/Then/Else.


a <= b (less than or equal to)

An object that performs an is less than or equal to operation on two operands.

Use

Use a <= b to determine whether the value(s) of one container is less than or equal to the value(s) of another container. The two containers may be of any shape. But if one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a scalar Int32, with the value 0 or 1. If the first operand is less than or equal to the second, the value of the result is 1; otherwise the value is 0.

Allowed Input Type Return Type

UInt8 | Int32
UInt16 | Int32
Int16 | Int32
Int32 | Int32
Int64 | Int32
Real32 | Int32
Real64 | Int32
Coord | Int32
Waveform | Int32
Text | Int32
Enum | Int32

If both operands are of type Coord, their independent variable(s) must be identical before the operation is even attempted; if not, an error is returned. Enums are converted to Text for the comparison. Text is compared using ASCII lexical ordering.

When two arrays are mapped against each other, each set of elements must satisfy the comparison operator for the operation to return 1.

Example

A scalar and an array: 3.0 <= [1, 3, 9] returns 0.

An array and a scalar: [1, 2, 4] <= 4 returns 1.

Two arrays: [1, 2, 3] <= [2, 3, 3] returns 1.

Two arrays: [1, 4, 3] <= [2, 3, 5] returns 0.

Two Coord scalars: coord(1,3) <= coord(1,5) returns 1.

Two Coord scalars: coord(1,3) <= coord(2,5) returns Values for independent variables must match.

Two Text scalars: "too" <= "zoo" returns 1.

Notes

If either of the containers is mapped (that is, of type Waveform, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Comparison
> <=

See Also

a ~= b (almost equal to), a AND b, a == b (equal to), a > b (greater than), a >= b (greater than or equal to), a < b (less than), NOT a, a != b (not equal to), a OR b, Comparison, a XOR b, Comparator, Conditional, and If/Then/Else.


Linear Regression

An object used to fit a linear regression line to (x,y) data.

Use

Use the linear regression to fit a straight line to the data using the equation y = C0 + C1*x, where x is the x coordinate and C0 and C1 are calculated coefficients. This type of regression should be thought of as fitting the best straight line through the data.

The linear regression object expects an array of Coord type of input with one independent variable, that is, an (x,y) pair. If the input array is not a Coord type, an attempt is made to convert it to Coord. If the input data is mapped (Waveform, Spectrum, or a mapped array) then the conversion to Coord uses the mapping information to create the x part of the (x,y) pairs. If the input data is not mapped (for example, an array), then the x part of the (x,y) pair is implicitly generated from its position in the array.

Open View Parameters

The Fit Type field on the open view is used to change the regression type to linear, logarithmic, exponential, power curve or polynomial regression. Clicking on the field will bring up a list of the different regression types.

Example

See Regression for a Coord conversion example.

Notes

See Regression for general notes on regression.

Location

Device [image] Regression

then select the appropriate Fit Type from the Fit Type field on the dialog box.

See Also

Regression, exponential regression, logarithmic regression, meanSmooth (x,numPts), movingAvg (x,numPts), polynomial regression, polySmooth (x), power curve regression, and Build Coord.


lockPosition()

An object that prevents the UserFunction panel that is being shown from being moved.

Use

When you use showPanel() to display a UserFunction panel, and have used unlockPosition() or have unchecked the PopupMoveable property to allow the user to move the panel, use lockPosition() to prevent the user from moving the panel.

Open View

You must include the text lockPosition(). Inside the parenthesis, you type the following parameter:

"UFname" - The name of the UserFunction. You must have double quotes around this name. This parameter is required.

You may add a data input pin to the lockPosition() object to set the UserFunction name, but you must replace "UFname" with the input terminal name.

Notes

The lockPosition() object is simply a Formula object initialized without inputs and containing the lockPosition() equation. You may also type lockPosition() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Panel
> lockPosition

See Also

Call, hidePanel(),
 panelPosition(), panelSize(),
 showPanel(), unlockPosition(),
 and UserFunction.


log(x)

An object that returns the natural logarithm of the value of x.

Use

Use log(x) to generate the natural logarithm (base e) of a number x. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

log([10, 2]) will return [2.302585092994, 0.693147180559945].

log((1,2)) will return (0.804718956, 1.10714872).

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> log

See Also

exp(x), exp10(x), a ^ b (exponent), log10(x), and Power.


log10(x)

An object that returns the common logarithm of the value of x.

Use

Use log10(x) to generate the common logarithm (base 10) of a number x. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

log10([10, 2]) will return [1, 0.301029995663981].

log10((1,2)) will return [0.349485, 0.480828579].

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> log10

See Also

exp(x), exp10(x), a ^ b (exponent), log(x), and Power.


Logarithmic Regression

An object used to fit a logarithmic curve to data.

Use

Use the logarithmic regression to fit the data to the equation:

y = C0 + C1*log(x)

where x is the x coordinate and C0 and C1 are calculated coefficients. The log function is the natural logarithm. The input data (x) must always be greater than zero.

The logarithmic regression object expects an array of Coord type of input with one independent variable, that is, an (x,y) pair. If the input array is not a Coord type, an attempt is made to convert it to Coord. If the input data is mapped (Spectrum or a mapped array) then the conversion to Coord uses the mapping information to create the x part of the (x,y) pairs. If the input data is not mapped (for example, an array), then the x part of the (x,y) pair is implicitly generated from its position in the array.

Open View Parameters

The Fit Type field on the open view is used to change the regression type to linear, logarithmic, exponential, power curve or polynomial regression. Clicking on the field will bring up a list of the different regression types.

Example

See Regression for a Coord conversion example.

Notes

See Regression for general notes on regression.

This function will not work for unmapped arrays. Unmapped arrays are converted to Coord starting with x=0, which will fail in the log function. This function will not work with a Waveform for the same reason.

Location

Device [image] Regression

then select the appropriate Fit Type from the Fit Type field on the dialog box.

See Also

Regression, exponential regression, meanSmooth (x,numPts), movingAvg (x,numPts), polynomial regression, polySmooth (x), power curve regression, and Build Coord.


Logical

A Category of Operators on the Function & Object Browser tool window.

Use

Use Logical to access the following objects which perform logical operations on operands:

a AND b

a OR b

a XOR b

NOT a

Notes

If logic requirements are met, a 1 is returned. If logic requirements are not met, a 0 is returned.

Note that the return value is of type Int32 and is the same shape as the operands. This is different than the conditionals, such as ==, that always return a scalar.

The logical operators are defined for type Text only in the sense of whether the string is null or not. That is, "zoo" AND "" (null string) is logically false since the second string is null. Remember that when comparing a Text type to a non-string type, the latter is promoted to a Text type. This means that "zoo" AND 0 is true since the real 0 is promoted to the string "0" and, since both strings are non-null, the AND expression is true and returns 1.

Location

Device [image] Function & Object Browser [image]  Operators [image]  Logical

See Also

a AND b, NOT a, a OR b, a XOR b, Comparison, Conditional, and If/Then/Else.


logMagDist (x,from,thru, logStep)

An object used to calculate the distribution of numbers in the input container given a logarithmic distribution.

Use

Use logMagDist(x,from,thru,logStep) to calculate a distribution of the log10 values of the values in the input array. The distribution is done in the range of from to thru by a size of logStep. The logStep parameter is the sub-range size in the log10 domain into which the log values are sorted (for example, a logStep of 0.2 would be equivalent to 5 sub-ranges per decade).

The x input may be of any size, and the shape must be an Array. For Complex, PComplex, and Spectrum type inputs, the magnitude of the complex number is calculated first, then that magnitude is used in determining the frequency distribution.

Allowed Input Type Return Type

UInt8 | Real64 Array 1D
UInt16 | Real64 Arrary 1D
Int16 | Real64 Array 1D
Int32 | Real64 Array 1D
Int64 | Real64 Array 1D
Real32 | Real64 Array 1D
Real64 | Real64 Array 1D
Coord | Real64 Array 1D
Waveform | Real64 Array 1D
Complex | Real64 Array 1D
PComplex | Real64 Array 1D
Spectrum | Real64 Array 1D

Since log10(x) is not defined for values of x<=0, the input values should be positive.

For input of all types, a Real64 Array 1D is returned. Each array element represents how many of the input value will fit in each distribution range.

The from, thru and logStep parameters must be Scalar in shape and of type Real64 or be able to be converted to Real64.

The from parameter must be less than the thru parameter.

The logStep parameter must be greater than zero.

Example

logMagDist(x,1,100,1), where x is the array:

[1, 2, 3, 10, 40, 50, 100, 100 ,100]

returns the array [3, 6]. In this example there are 2 sub-ranges ranging from 1 to 2 by 1. The output array shows how many of the input numbers fall into each range.

Notes

The sub-ranges for the distribution are determined by the following range parameters:

Range 1

Range Minimum: "from" parm

range: <= range1

Range Maximum: < "from" parm + "step" parm(range1limit)

Range 2

Range Minimum: range1limit

range: <= range2

Range Maximum: < range1limit + "step" parm (range2limit)

Range 3

Range Minimum: range2limit

range: <= range3

Range Maximum: < range2limit + "step" parm (range3limit)

Range n-1

Range Minimum: range(n-2)limit

range: <= range(n-1)

Range Maximum: <= "thru" parm

The log10 of the "from" and "thru" parameters is calculated before determining the range distribution.

Mappings on the operands are ignored and the return value is not mapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> logMagDist

See Also

magDist(x, from,thru, step).


logRamp (numElem, from,thru)

An object that generates a logarithmically ramped array.

Use

Use logRamp(numElem,from,thru) to generate a Real64 one-dimensional array of length numElem, with the values logarithmically ramped from from to thru. numElem must be a scalar container which is, or can be converted to, Int32 and with a value greater than zero. from and thru must be scalar containers which are, or can be converted to, Real. If from is less than thru the ramping is positive; otherwise it automatically ramps negatively. Both from and thru must have values greater than zero.

Example

logRamp(3, 1, 100) returns a 1D Array with values [1, 10, 100].

Notes

The return value has no mappings.

The algorithm for generating values is:

Y[I]=exp10(log10(from)+I*((log10(thru)-log10(from))/numElem-1))
for I=0..numElem-1

This has the effect that the last element in the resultant array has the value thru.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Generate
> logRamp

See Also

Alloc Real64 and ramp (numElem, from,thru).


mag(x)

An object that returns the magnitude of a PComplex number x.

Use

Use mag(x) to extract the magnitude of a PComplex number x. For types Integer, Real, Coord, and Waveform, the same type with the same value(s) is returned. For types Complex, PComplex, and Spectrum, mag(x) returns a Real container with the value of the magnitude of the PComplex number. (Complex is first converted to PComplex.)

Allowed Input Type Return Type

UInt8 | UInt8, with the same value
UInt16 | UInt16, with the same value
Int16 | Int16, with the same value
Int32 | Int32, with the same value
Int64 | Int64, with the same value
Real32 | Real32, with the same value
Real64 | Real64, with the same value
Coord | Coord, with the same values
Waveform | Waveform, with the same values
Complex | Real64
PComplex | Real64
Spectrum | Real64

Example

mag( (1,@45) ) returns 1.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Complex Parts
> mag

See Also

conj(x), im(x), j(x), phase(x), re(x), Real Parts, Build Complex, Default Preferences, and UnBuild Complex.


magDist(x, from,thru, step)

An object used to calculate the distribution of numbers in the input container.

Use

Use magDist(x,from,thru,step) to calculate a distribution of numbers in the input array. The distribution is done in the range of from to thru by a size of step. The step parameter is the size of the range of the sub-array that the numbers will go into.

The x input may be of any size. For Complex, PComplex, and Spectrum type inputs, the magnitude of the complex number is calculated first, then that magnitude is used to calculate the frequency distribution. The x input shape must be an Array.

Allowed x Input Type Return Type

UInt8 | Real64 Array 1D
UInt16 | Real64 Array 1D
Int16 | Real64 Array 1D
Int32 | Real64 Array 1D
Int64 | Real64 Array 1D
Real32 | Real64 Array 1D
Real64 | Real64 Array 1D
Coord | Real64 Array 1D
Waveform | Real64 Array 1D
Complex | Real64 Array 1D
PComplex | Real64 Array 1D
Spectrum | Real64 Array 1D

Each element in the returned array represents how many of the input values will fit in each distribution range.

The from, thru and step parameters must be Scalar in shape and of type Real64 or be able to be converted to Real64.

The from parameter must be less than the thru parameter.

The step parameter must be greater than zero.

Example

magDist(x,1,5,1), where x is the array [1, 2, 3, 4, 5, 5, 3, 3, 3, 2, 2, 2], returns the array [1, 4, 4, 3]. In this example there are four sub-ranges ranging from 1 to 5 by 1. The output array shows how many of the input numbers fall into each sub-range.

Notes

The sub-ranges for the distribution are determined by the following range parameters:

Range 1

Range Minimum: "from" parm

range: <= range1

Range Maximum: < "from" parm + "step" parm(range1limit)

Range 2

Range Minimum: range1limit

range: <= range2

Range Maximum: < range1limit + "step" parm (range2limit)

Range 3

Range Minimum: range2limit

range: <= range3

Range Maximum: < range2limit + "step" parm (range3limit)

Range n-1

Range Minimum: range(n-2)limit

range: <= range(n-1)

Range Maximum: <= "thru" parm

Mappings on the operands are ignored and the return value is not mapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> magDist

See Also

logMagDist (x,from,thru, logStep).


matDivide (numer, denom)

This object will divide two matrices A and B. The matDivide(numer,denom) operation is defined in algebraic terms as A/B; but in matrix (linear algebraic) terms, it is defined as inv(B)*A.

Use

Use the matDivide(numer,denom) to divide one matrix into another. Given the linear system BX=A, where the B and A matrices are known, solve for the solution matrix X. In algebraic terms the solution is to solve for X by dividing A by B: X = A/B. But, by solving the system of equations with linear algebraic matrix rules, the operation is really X = inv(B)*A. This operation is useful to find the solution of a linear system of n equations in n unknowns.

If B is an n x n (square) matrix, then the linear system BX = A is a system of n equations in n unknowns. Suppose that B is non-singular. Then inv(B) (inverse of B) exists and multiplying BX = A by inv(B) on both sides, obtains X = inv(B)*A.

The solution to the multiplication of inv(B)*A is the solution to the given linear system. If B is nonsingular, then there is a unique solution to the system.

Example

matDivide(A,B), where A is a 3x1 matrix [ [8], [24], [8] ]
and B is an 3x3 matrix [ [1, 1, 1], [0, 2, 3], [5, 5, 1] ]
returns a 3x1 matrix [ [0], [0], [8] ].

Notes

Mappings on the operand are ignored and the return value is not mapped.

matDivide(A,B) uses the inverse of B; hence, B must be a square matrix. The rules for matMultiply(A,B) apply to the inv(B) * A operation.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Matrix
> matDivide

See Also

a / b (divide) and matMultiply (A,B).


matMultiply (A,B)

An object used to multiply two matrices together according to linear Algebra rules.

Use

Use matMultiply(A,B) to multiply together the two input matrices A and B. Let A be an m x p matrix and B be a p x n matrix. The matMultiply of A and B is a new matrix, Z, that is an m x n matrix. Notice that the multiplication is defined if and only if the matrices are of the sizes where A is an m x p matrix and B is a p x n matrix (that is, where the number of rows of the second matrix equals the number of columns of the first).

The input matrices must be of matrix shape. If the two matrices are not of the same type, the lower type matrix is promoted to the higher type and the return value is of the higher type.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Complex

PComplex

Example

matMultiply(A,B), where A is an 2x1 matrix [ [3], [1] ] and B is a 1x2 matrix [2, 4], returns a 2x2 matrix [ [6, 12], [2, 4] ].

Notes

Mappings on the operand are ignored and the return value is not mapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Matrix
> matMultiply

See Also

matDivide (numer, denom) and a * b (multiply).


Matrix

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use the Matrix operations to calculate common linear algebra operations on matrices.

det(x)

inverse(x)

transpose(x)

identity(x)

minor(x,row,col)

cofactor(x,row,col)

matMultiply(A,B)

matDivide(numer,denom)

Location

Device [image] Function & Object Browser [image]  Built-in Functions [image] Matrix

See Also

cofactor(x, row,col), det(x), identity(x), inverse(x), matMultiply (A,B), matDivide (numer, denom), minor(x,row, col), and transpose(x).


max(x)

An object used to return the maximum value in the input container.

Use

Use max(x) to return the maximum value in the container.

The x input may be of any size and shape. For Coord input types, the operation is done on the dependent variable. For Text input types, the max(x) text string is the one that is the highest lexically ordered string.

Allowed Input Type Return Type

UInt8 | UInt8, Scalar in shape
UInt16 | UInt16, Scalar in shape
Int16 | Int16, Scalar in shape
Int32 | Int32, Scalar in shape
Int64 | Int64, Scalar in shape
Real32 | Real32, scalar in shape
Real64 | Real64, scalar in shape
Coord | Coord, Scalar in shape
Waveform | Real 64, Scalar in shape
Text | Text, Scalar in shape

Example

max(x), where x is the array [5, 34, 1, 54, 6, 2, 9, 7, 16, 42], returns 54.

To calculate the value of two scalars, use the array build syntax to create an array and call max() on the array. For example:

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> max

See Also

maxIndex(x), maxX(x), mean(x), median(x), min(x), mode(x), rms(x), sdev(x), and vari(x).


maxIndex(x)

An object used to return the index in the input array of the largest element.

Use

Use maxIndex(x) to return the index of the largest element in a 1D array. The x input must be of Array 1D shape.

Allowed Input Type Return Type

UInt8 | Int32
UInt16 | Int32
Int16 | Int32
Int32 | Int32
Int64 | Int32
Real32 | Int32
Real64 | Int32
Coord | Int32
Waveform | Int32
Text | Int32

Example

Applying the maxIndex(x) to an array, where x is the array [.1, .4, .6, .9] returns 3 because .9 is the largest element of the array.

maxIndex(x) of ["Ken", "Sue", "Randy", "Bill", "Doug"] returns 1 because "Sue" is the highest lexically ordered term.

Notes

Note that array indices start with zero.

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> maxIndex

See Also

max(x), maxX(x), min(x), minIndex(x), and minX(x).


maxX(x)

An object used to return the x value of a maximum point of the input Array 1D where the array is mapped.

Use

Use maxX(x) to return the Xindex of the largest element in a 1D (linear) array. The x input must be of Array 1D shape.

Allowed Input Type Return Type

UInt8 | Real64 Scalar
UInt16 | Real64 Scalar
Int16 | Real64 Scalar
Int32 | Real64 Scalar
Int64 | Real64 Scalar
Real32 | Real64 Scalar
Real64 | Real64 Scalar
Coord | Real64 Scalar
Waveform | Real64 Scalar
Text | Real64 Scalar

If the data is mapped, the value returned is the x value corresponding to the maximum y value of the input data. The x value is calculated using the array mappings. If the data is not mapped, then the value returned is the index in the array of the maximum y value. That is, it will return the (implicit) position in the array of maximum x value.

The Coord type returns the independent variable x at the maximum y value.

This function is only useful for mapped data or Coord types, as it is the same as maxIndex(x) for unmapped data.

Example

Take the maxX(x) of a sine waveform type that has 256 points and is mapped over 0 to 20 milliseconds. The return value is .009219.

Take the maxX(x) of an array, where x is the unmapped array. [.1, .4, .6, .9] returns 3 because .9 is the largest element of the array. This is identical to maxIndex(x).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> maxX

See Also

max(x), maxIndex(x), min(x), minIndex(x), minX(x), Get Mappings, and Set Mappings.


mday(aDate)

An object that returns the day of the month of the time x.

Use

Use mday(x) to transform the given time x into a container of the same shape as x with value(s) 1 - 31 corresponding to the day of the month.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

mday(dmyToDate(25,12,1991)) returns 25, the 25th day of the month.

Notes

mday(aDate) returns 1-31, not 0-30. This is one of the few non-zero based functions in VEE. Mappings are retained in the return value.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> mday

See Also

dmyToDate (d,m,y), hmsToHour (h,m,s), hmsToSec (h,m,s), month(aDate), now(), Time & Date, wday(aDate), and year(aDate).


mean(x)

An object used to calculate the mean value of the data in the input container.

Use

Use mean(x) to return the mean (average) value of the container. The numbers in the input container are added, then the sum is divided by the number of elements in the input. The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | Real64 Scalar
UInt16 | Real64 Scalar
Int16 | Real64 Scalar
Int32 | Real64 Scalar
Int64 | Real64 Scalar
Real32 | Real64 Scalar
Real64 | Real64 Scalar
Coord | Real64 Scalar
Waveform | Real64 Scalar

For Coord input types, the operation is done on the dependent variable.

Example

Where x is the array [1, 2, 3, 11, 12, 34], mean(x) returns 10.5.

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> mean

See Also

max(x), median(x), min(x), mode(x), rms(x), sdev(x), and vari(x).


meanSmooth (x,numPts)

An object used to smooth input data using the mean of a specified number of data points surrounding the data point of interest to calculate the smoothed data point.

Use

Use meanSmooth(x,numPts) to perform a data smoothing similar to the polySmooth(x) routine. The algorithm calculates an arithmetic mean of the numPts data points around the point to be smoothed. For example, if numPts is 5, take the mean of: 2 points before the current point, the current point, and two points after the current point. If numPts is even, the algorithm will add one more to the number of points to make it odd. The x input must be of Array 1D shape.

Allowed x Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

The independent variables of a Coord input type must be equidistant, that is, the x-interval between adjacent points must be a constant. The smoothing is only done on the dependent variable (the y data of the Coord).

The noise suppression capability of this technique is a function of the size numPts of the averaging which you specify. Large values of numPts will suppress noise to a much greater degree than small values of numPts. Quite often this function can be used to dramatically improve the results of other functions (like deriv(x,order)) if used to preprocess the data.

Notes

Mappings on input parameters are ignored and the output has the same mappings as the input parameter x.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> meanSmooth

See Also

movingAvg (x,numPts), polySmooth (x), Regression types, and Signal Processing.


median(x)

An object used to calculate the median value of the input container.

Use

Use median(x) to return the middle value of the container. The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | Real64 Scalar
UInt16 | Real64 Scalar
Int16 | Real64 Scalar
Int32 | Real64 Scalar
Int64 | Real64 Scalar
Real32 | Real64 Scalar
Real64 | Real64 Scalar
Coord | Real64 Scalar
Waveform | Real64 Scalar

For Coord input types, the operation is done on the dependent variable.

Example

median([1, 2, 3, 8, 20]) returns 3.

median(x), where x is the array [1, 2, 5, 11, 12, 33], returns 8. The median value is the one in the middle of the range of numbers. In the case where there are an even number of numbers, the median is calculated as the average between the two middle numbers. In this case, the median value is the average of 5 and 11, which is 8.

median([20, 5, 10]) returns 10.

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> median

See Also

max(x), mean(x), min(x), mode(x), rms(x), sdev(x), and vari(x).


min(x)

An object used to return the minimum value in the input container.

Use

Use min(x) to return the minimum value in the container. The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | UInt8, Scalar in shape
UInt16 | UInt16, Scalar in shape
Int16 | Int16, Scalar in shape
Int32 | Int32, Scalar in shape
Int64 | Int64, Scalar in shape
Real32 | Real32, Scalar in shape
Real64 | Real64, Scalar in shape
Coord | Coord, Scalar in shape
Waveform | Real64, Scalar in shape
Text | Text, Scalar in shape

For Coord input types, the operation is done on the dependent variable. For Text input types, the min(x) text string is the one that is the lowest lexically ordered string.

Example

min(x), where x is the array [5, 34, 1, 54, 6, 2, 9, 7, 16, 42], returns 1.

To calculate the value of two scalars, use the array build syntax to create an array and call mix() on the array. For example:

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> min

See Also

max(x), mean(x), median(x), minIndex(x), minX(x), mode(x), rms(x), sdev(x), and vari(x).


minIndex(x)

An object used to return the index in the input array of the smallest element.

Use

Use minIndex(x) to return the index of the smallest element in a 1D array. The x input must be of Array 1D shape.

Allowed Input Type Return Type

UInt8 | Int32
UInt16 | Int32
Int16 | Int32
Int32 | Int32
Int64 | Int32
Real32 | Int32
Real64 | Int32
Coord | Int32
Waveform | Int32
Text | Int32

Example

Applying the minIndex(x) to an array, where x is the array [.1, .4, .6, .9] returns 0 because .1 is the smallest element of the array.

minIndex(x) of ["Ken", "Randy", "Doug", "Bill", "Sue"] returns 3 because "Bill" is the lowest lexically ordered term.

Notes

Note that array indices start with zero.

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> minIndex

See Also

max(x), maxIndex(x), maxX(x), min(x), and minX(x).


minor(x,row, col)

An object used to calculate the minor of a matrix x at row r and column c.

Use

Use minor(x,row,col) to calculate the minor of the square input matrix x. The minor of matrix is defined as the determinant of the submatrix of the input matrix x obtained by deleting the rth row and cth column. The x input must be a square matrix shape (same number of rows as columns). The input for the row and column to delete, r and c, must be Int32 Scalar or be able to be converted to Int32 type.

Allowed x Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Complex | Complex, Scalar in shape
PComplex | PComplex, Scalar in shape

Example

minor(a,1,2), where a is a matrix [ [3, -1, 2], [4, 5, 6], [7, 1, 2] ],
returns -34.

Notes

Mappings on the operand are ignored.

The r and c inputs are expected to be of type Int32 or be able to be converted to that type. The rows and columns of the matrix are numbered from 0 to n-1 so be careful when specifying which row and column to use.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Matrix
> minor

See Also

cofactor(x, row,col) and det(x).


minX(x)

An object used to return the x value of the minimum point of the input Array 1D where the array is mapped.

Use

Use minX(x) to return the Xindex of the smallest y element in an 1D (linear) array. The x input must be of Array 1D shape.

Allowed Input Type Return Type

UInt8 | Real64 Scalar
UInt16 | Real64 Scalar
Int16 | Real64 Scalar
Int32 | Real64 Scalar
Int64 | Real64 Scalar
Real32 | Real64 Scalar
Real64 | Real64 Scalar
Coord | Real64 Scalar
Waveform | Real64 Scalar
Text | Real64 Scalar

If the data is mapped, the value returned is the x value corresponding to the minimum y value of the input data. The x value is calculated using the array mappings. If the data is not mapped, then the value returned is the index in the array of the minimum y value. That is, it will return the (implicit) position in the array of minimum x value.

The Coord type returns the independent variable x at the minimum y value.

This function is only useful for mapped data or Coord types. It is the same as minIndex(x) for unmapped data.

Example

Take the minX(x) of a sine waveform that has 256 points and is mapped over 0 to 20 milliseconds. The return value is .0107.

Take the minX(x) of an array, where x is the unmapped array. [.1, .4, .6, .9] returns 0 because .1 is the smallest element of the array. This is identical to minIndex(x).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> minX

See Also

max(x), maxIndex(x), maxX(x), min(x), minIndex(x), Get Mappings, and Set Mappings.


a mod b (modulo)

An object that performs an arithmetic modulo (remainder) of two operands.

Use

Use a mod b to determine the remainder of the division of two containers. The two containers may be of any shape. But if one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type, with the same shape as the operands.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. The modulo is only performed on the dependent (last) variable.

Example

A scalar modulo an array: 3.2 MOD [1, 2, 3] returns [0.2, 1.2, 0.2].

An array modulo a scalar: [1, 2, 3] MOD 2 returns [1, 0, 1].

Two Coord scalars: coord(1,3) MOD coord(1,5) returns coord(1,2).

Two Coord scalars: coord(1,3) MOD coord(2,5) returns an error.

Two scalars: 12.95 mod 2 returns 0.95.

Two scalars: 12.95 mod 2.1 returns 0.35.

Notes

If either of the containers is mapped (that is, of type Waveform, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Arithmetic
> MOD

See Also

a + b (add), a div b (truncated division), a / b (divide), a * b (multiply), and a - b (subtract).


mode(x)

An object used to calculate the mode of the data in the input container.

Use

Use mode(x) to return the mode of the value in the container. The mode value is the one which is found most often in the data. In case of bimodal data (two numbers represented the same number of times) or higher modes, mode(x) returns the lowest valued mode found in the array container.

In the case where there is no mode value (that is, every number is unique), the first value in the input container is returned.

The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Real64 Scalar
Waveform | Real64 Scalar

For Coord input types, the operation is done on the dependent variable.

Example

Single mode: where x is the array [2, 1, 12, 11, 2, 33], mode(x) returns 2.

Bimodal: where x is the array [2, 1, 2, 12, 11, 12], mode(x) returns 2.

No mode: where x is the array [3, 2, 1, 11, 12, 33], mode(x) returns 3.

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> mode

See Also

max(x), mean(x), median(x), min(x), rms(x), sdev(x), and vari(x).


month(aDate)

An object that returns the month of the year of the time x.

Use

Use month(aDate) to transform the given time x into a container of the same shape with value(s) 1 - 12 corresponding to the month of the year. x can be any shape, and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

month(dmyToDate(25,12,1991)) returns 12, the 12th month of the year.

Notes

month(aDate) returns 1-12, not 0-11. This is one of the few non-zero based functions in VEE. Mappings are retained in the return value.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> month

See Also

dmyToDate (d,m,y), hmsToHour (h,m,s), hmsToSec (h,m,s), mday(aDate), now(), Time & Date, wday(aDate), and year(aDate).


movingAvg (x,numPts)

An object used to smooth the input data using the average of a specified number of data points preceding the data point of interest to calculate the smoothed data point.

Use

Use movingAvg(x,numPts) to perform a data smoothing similar to the meanSmooth(x,numPts) routine. The algorithm calculates an arithmetic mean of numPts previous data points. The x input must be of Array 1D shape.

Allowed x Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

The independent variables of a Coord input type must be equidistant, that is, the x-interval between adjacent points must be a constant. The smoothing is only done on the dependent variable (the y data of the Coord).

This technique tends to represent more of a "historical" view of the data since, for any point in the array, the average value is calculated only from earlier points. This is in contrast to the average value being calculated from points on both sides of the point in question, as is the case for polySmooth(x) and meanSmooth(x,numPts).

Example

If numPts is 5, the average of the 4 previous points and the point of interest are used to determine what the smoothed point should be.

Notes

Mappings on input parameters are ignored and the output has the same mappings as the input parameter x.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> movingAvg

See Also

meanSmooth (x,numPts), polySmooth (x), Regression types, and Signal Processing.


a * b (multiply)

An object that performs an arithmetic multiplication on two operands.

Use

Use a * b to multiply the values of two containers. The two containers may be of any type and of any shape. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type, with the same shape as the operands.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

PComplex

Spectrum

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. The multiplication is only performed on the dependent (last) variable.

If one of the containers is Text, the other must be an Int32. Text multiplication consists of repeating the string the number of times given by the value of the Int32. Enums are converted to Text for multiplication.

This multiplication operation performs a parallel multiplication on all elements of the arrays, including matrices. For a matrix multiply, see the function matMultiply(A,B).

Example

Array times a scalar: [1, 2, 3] * 3 returns [3, 6, 9].

Two arrays: [4, 5, 6] * [1, 2, 3] returns [4, 10, 18].

Two PComplex scalars: (2,@45) * (3,@90) returns (6,@135) with Trig Mode set to Degrees.

Two Coord scalars: coord(1,3) * coord(1,5) returns coord(1,15).

Two Coord scalars: coord(1,3) * coord(2,5) returns an error.

Text times a scalar: "hello" * 3 returns "hellohellohello".

A Text array times an array: ["hello", "b"] * [3, 2] returns
["hellohellohello", "bb"].

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Arithmetic
> *

See Also

a + b (add), a / b (divide), matMultiply (A,B), and a - b (subtract).


NOT a

An object that performs a logical NOT operation on one operand.

Use

Use NOT a to determine the logical opposite of the value(s) of a container. The container may be of any type and of any shape. The result is an Int32 of the same shape as the operand, with value(s) 0 or 1. If the operand is false (zero), the value of the NOT operator is 1; otherwise the value is 0.

If the operand is of type Boolean, the result is a Boolean of the same shape as the operand.

For Coord containers, only the dependent (last) variable is considered for the NOT operation.

For Complex, PComplex, and Spectrum containers, the value of the operand is true if either part is non-zero. Text is true if non-null. Enums are converted to Text for the operation.

Example

A Boolean scalar: NOT False returns True.

A scalar: NOT 3 returns 0.

A scalar: NOT 0 returns 1.

An array: NOT [-3, 0, 3] returns [0, 1, 0].

A PComplex scalar: NOT (1,@90) returns 0.

A Complex scalar: NOT (0,1) returns 0.

A Complex scalar: NOT (0,0) returns 1.

A Coord scalar: NOT coord(1,3) returns 0.

A Coord scalar: NOT coord(1,0) returns 1.

A Text scalar: NOT "too" returns 0.

A Text scalar: NOT "" returns 1.

Notes

The result has the same mapping as the operand.

Note that the If/Then/Else device requires the expression(s) inside it to evaluate to either a scalar or an array, which is either all zeros or all ones.

Location

Device [image] Function & Object Browser

>  Operators
> Logical
> NOT

See Also

Conditional and If/Then/Else.


a != b (not equal to)

An object that performs an is not equal to operation on two operands.

Use

Use a != b to determine whether the value(s) of one container is not equal to the value(s) of another container. The two containers may be of any type and of any shape. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a scalar Int32 with the value 0 or 1. If the first operand is not equal to the second, the value of the result is 1; otherwise the value is 0.

For Coord containers, if any of the independent variable(s) do not match exactly, an error is returned. For Complex, PComplex, and Spectrum containers, if either part or both parts do not match, the result is 1. Enums are converted to Text for the comparison.

Arrays must have one or more of their respective values not equal for the result to be 1.

If both operands are of type Boolean, the result is a Boolean of the same shape as the operands.

Example

Two Boolean scalars: True != False returns True.

A scalar and an array: 3.0 != [3, 3, 3] returns 0.

A scalar and an array: 3.0 != [3, 1, 3] returns 1.

Two arrays: [1, 2, 3] != [1, 2, 4] returns 1.

Two PComplex scalars: (1,@90) != (1,@85) returns 1.

Two Complex scalars: (2,3) != (2,4) returns 1.

Two Complex scalars: (2,3) != (2,3) returns 0.

Two Coord scalars: coord(1,3) != coord(1,5) returns 1.

Two Coord scalars: coord(1,3) != coord(2,3) returns Values for independent variables must match.

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Comparison
> !=

See Also

a ~= b (almost equal to), a AND b, a == b (equal to), a > b (greater than), a >= b (greater than or equal to), a < b (less than), a <= b (less than or equal to), NOT a, a OR b, Comparison, a XOR b, Comparator, and Conditional.


now()

An object that returns the current time.

Use

Use now() to generate a Real64 scalar container with the value of the current time. The value of the Real64 is the number of seconds since 00:00 hours 1 January 0001 AD given in UTC.

Example

now() returns around 62.802G.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> now

See Also

dmyToDate (d,m,y), hmsToHour (h,m,s), hmsToSec (h,m,s), mday(aDate), month(aDate), Time & Date, wday(aDate), and year(aDate).


a OR b

An object that performs a logical OR operation on two operands.

Use

Use a OR b to determine whether the value(s) of either of two containers is logically true (non-zero). The two containers may be of any type and of any shape. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is an Int32 of the same shape as the operands, with value(s) 0 or 1. If either or both operands are non-zero, the value of the OR operation is 1; otherwise the value is 0.

If both operands are of type Boolean, the result is a Boolean of the same shape as the operands.

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. Only the dependent (last) variable is considered for the OR operation.

For Complex, PComplex, and Spectrum containers, the value of the operand is true if either part is non-zero. Text is true if non-null. Enums are converted to Text for the operation.

Example

Two Boolean scalars: True OR False returns True.

A scalar and an array: 3 OR [3, 3, 3] returns [1, 1, 1].

A scalar and an array: 0 OR [-3, 0, 3] returns [1, 0, 1].

Two arrays: [1, 0, 0] OR [0, 1, (-1)] returns [1, 1, 1].

Two PComplex scalars: (1,@90) OR (1,@85) returns 1.

Two Complex scalars: (0,0) OR (0,1) returns 1.

Two Complex scalars: (0,1) OR (1,0) returns 1.

Two Complex scalars: (0,0) OR (0,0) returns 0.

Two Coord scalars: coord(1,3) OR coord(1,5) returns 1.

Two Coord scalars: coord(1,3) OR coord(2,3) returns an error.

A Text scalar and a scalar number: "too" OR 0 returns 1.

A Text scalar and a scalar number: "" OR 0 returns 1 because the 0 is promoted to the string "0", which is non-null.

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Note that the If/Then/Else device requires the expression(s) inside it to evaluate to either a scalar or an array, which is either all zeros or all ones.

Location

Device [image] Function & Object Browser

>  Operators
> Logical
> OR

See Also

a AND b, NOT a, Comparison, a XOR b, Conditional, and If/Then/Else.


ordinal(x)

An object that returns the ordinal value of x.

Use

Use ordinal(x) to obtain the ordinal value of a container. x may be any shape. For integers, reals, Coord, and Waveform, the result is the same as the argument with the same mappings.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform
Enum | Int32

For Enum, the result is an Int32 of the same shape as x with the value of the ordinal value of the Enum. Enums created from the Enum Constant have their ordinal values starting at 0 and going to n-1, where n is the number of Enum values in the list.

Example

If an Enum constant is created with the strings ordered "a", "b", and "c", and the current value "a" is selected, ordinal(x) on that container would return 0 since the first value is selected. Remember that VEE is zero-based. If, with the same Enum constant, the currently selected value is "c", then ordinal(x) on that container would return 2, the offset of the currently selected value.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Real Parts
> ordinal

See Also

Complex Parts, Selection Control, and Real Parts.


panelPosition()

An object that outputs the location of a UserFunction panel.

Use

When you use showPanel() to display a UserFunction panel, use panelPosition() to output the location of the panel. The output is a Coord that contains the location of the upper-left corner of the UserFunction panel (excluding the border and title area, if they exist on the panel) as the number of pixels from the upper-left corner of the work area.

Open View

You must include the text panelPosition(). Inside the parenthesis, you type the following parameter:

"UFname" - The name of the UserFunction. You must have double quotes around this name. This parameter is required.

You may add a data input pin to the panelPosition() object to set the UserFunction name, but you must replace "UFname" with the input terminal name.

Notes

If the UserFunction does not have a panel view or the panel view has not yet been shown in the program, panelPosition() returns the Coord (0, 53).

If the UserFunction panel is not currently shown, panelPosition() returns the panel position of the last time it was shown.

The panelPosition() object is simply a Formula object initialized without inputs and containing the panelPosition() equation. You may also type panelPosition() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Panel
> panelPosition

See Also

Call, hidePanel(),
 lockPosition(), panelSize(),
 showPanel(), unlockPosition(),
 and UserFunction.


panelSize()

An object that outputs the size of a UserFunction panel.

Use

When you use showPanel() to display a UserFunction panel, use panelSize() to output the size of the panel. The output is a Coord that contains the size of the UserFunction panel in pixels. The size does not include the size of the border and title area (if they exist on the panel).

Open View

You must include the text panelSize(). Inside the parenthesis, you type the following parameter:

"UFname" - The name of the UserFunction. You must have double quotes around this name. This parameter is required.

You may add a data input pin to the panelSize() object to set the UserFunction name, but you must replace "UFname" with the input terminal name.

Notes

If the UserFunction does not have a panel view or the panel view has not yet been shown in the program, panelSize() returns the Coord (0, 0).

If the UserFunction panel is not currently shown, panelSize() returns the panel size from the last time it was shown.

The panelSize() object is simply a Formula object initialized without inputs and containing the panelSize() equation. You may also type panelSize() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Panel
> panelSize

See Also

Call, hidePanel(),
 lockPosition(), panelPosition(),
 showPanel(), unlockPosition(),
 and UserFunction.


perm(n,r)

An object used to calculate the permutations of n numbers taken r at a time.

Use

Use perm(n,r) to calculate the number of permutations of n things taken r at a time using the formula:

Perm(n, r) = n! / (n - r)!

The ! symbol means factorial. The n input may be of any shape and size. The second r parameter must be of the same type or be able to be converted to the same type as the n input value. If both of the inputs are arrays, they must be of exactly the same shape and size.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

The perm(n, r) operation is only defined for integer operands so the input values, while of unique type, are converted to Int32 type before the calculation is done.

Example

perm(10,3) will return 720 as given by the formula
10!/(10-3)! = 10!/7! = 10*9*8 = 720.

perm(10.4,3.9) will return 5040 as given by the formula
10!/(10-4)! = 10!/6! = 10*9*8*7 = 5040. The rule about converting a real to Int32 forces 10.4 to 10 and 3.9 to 4.

Notes

Both n and r must be positive and n must be greater than r. If both of the inputs are mapped, then the mappings must be the same. The return value has the same mappings as the input if either input is mapped. If neither of the inputs is mapped, then the output is unmapped.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> perm

See Also

beta(x,y), binomial(a,b), comb(n,r), factorial(n), and gamma(x).


phase(x)

An object that returns the phase of a PComplex number x.

Use

Use phase(x) to extract the phase of a PComplex number x. x can be any shape. For types Complex, PComplex, and Spectrum, phase(x) returns a Real64 container with the value of the polar phase angle of the PComplex number. (Complex is first converted to PComplex.)

Allowed Input Type Return Type

UInt8 | UInt8, value of zero
UInt16 | UInt16, value of zero
Int16 | Int16, value of zero
Int32 | Int32, value of zero
Int64 | Int64, value of zero
Real32 | Real32, value of zero
Real64 | Real64, value of zero
Coord | Coord, value of zero
Waveform | Waveform, value of zero
Complex | Real64
PComplex | Reail64
Spectrum | Real64

The phase(x) value is returned in the units of the current Trig Mode.

Example

phase((1,@45)) returns 45.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Complex Parts
> phase

See Also

conj(x), im(x), j(x), mag(x), re(x), Real Parts, Build PComplex, Default Preferences, and UnBuild PComplex.


poly(x,vec)

A summary notation for objects poly(x,[a0, a1]), poly(x,[a0, a1, a2]), poly(x,[a0, a1, a2, a3]), and poly(x,[a0, a1, ... aN]). These objects return the polynomial value of the x and vec values.

Use

Use poly(x,vec) to generate the polynomial result of the x data and vec coefficients. x can be any shape and the same shape is returned. vec must be either a scalar or a one-dimensional array. poly(x,vec) takes the elements of vec as the polynomial coefficients, and x as the data. vec starts with a0, then a1, and so on, out to the length of vec.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64

The polynomial equation computes:

a0 + a1*x + a2*x*x + a3*x*x*x + ...

Example

poly([10, 2], [3, 2, 4]) generates [423, 23].

Notes

Mappings of the resultant container are the same as the input container x.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> poly

See Also

ramp (numElem, from,thru).


Polynomial Regression

An object used to fit a polynomial curve of arbitrary degree to (x,y) data.

Use

Use the polynomial regression to fit the data to the equation
y = C0 + C1*x + C2*x^2 + ... , where x is the x coordinate and C0, C1, and so forth, are calculated coefficients. Polynomial curve fitting requires the degree of the polynomial to be set on the Order input field on the regression object.

The polynomial regression object expects an array of Coord type of input with one independent variable, that is, an (x,y) pair. If the input array is not a Coord type, an attempt is made to convert it to Coord. If the input data is mapped (Waveform, Spectrum, or a mapped array), then the conversion to Coord uses the mapping information to create the x part of the (x,y) pairs. If the input data is not mapped (for example, an array), then the x part of the (x,y) pair is implicitly generated from its position in the array.

Open View Parameters

The Fit Type field on the open view is used to change the regression type to linear, logarithmic, exponential, power curve or polynomial regression. Clicking on the button will bring up a list of the different regression types.

The Order input field is used to set the order of the polynomial to which the data is fitted. The order of the polynomial fit must be greater than or equal to one. A polynomial fit of order one fits the data to a straight line and is the same as the linear regression choice.

Example

See Regression for a Coord conversion example.

Notes

See Regression for general notes on regression.

Location

Device [image] Regression

then select the appropriate Fit Type from the Fit Type field on the dialog box.

See Also

Regression, exponential regression, linear regression, logarithmic regression, meanSmooth (x,numPts), movingAvg (x,numPts), polySmooth (x), power curve regression, and Build Coord.


polySmooth (x)

An object used to smooth data using a polynomial fit of the data.

Use

Use polySmooth(x) to smooth out data. A fourth order polynomial is fitted to the data and a new data point is calculated based on the curve fit using the polynomial. To do the 4th order curve fit, 5 points are used, two on either side of the data point being fitted and the data point itself, with special consideration for the two end points. The x input must be of Array 1D shape.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

The independent variables of a Coord input type must be equidistant. That is, the x-interval between adjacent points must be a constant. The smoothing is only done on the dependent variable (the y data of the Coord).

Notes

The method used is to take a 5-element sliding window and apply the standard formula for a 4th-degree Stirling collocation polynomial. Refer to Francis Scheid, Schaum's Outline of Theory and Problems of Numerical Analysis, McGraw Hill, New York, NY, 1968. ISBN #07-055197-9.

Mappings on the operand are ignored and the output container has the same mappings as the input.

The filtering operation which results from this technique has a fixed "frequency response" which suppresses only the noisiest part of the data. If more noise suppression is required, see the meanSmooth(x,numPts) function, which you can use to suppress much more noise.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Data Filtering
> polySmooth

See Also

meanSmooth (x,numPts), movingAvg (x,numPts), Regression types, and Signal Processing.


Power

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Power to access the following objects which perform power functions such as square root, square, log, exp, and log base 10.

sq(x)

sqrt(x)

cubert(x)

recip(x)

log(x)

log10(x)

exp(x)

exp10(x)

Location

Device [image] Function & Object Browser [image] Built-in Functions [image] Power

See Also

cubert(x), exp(x), exp10(x), log(x), log10(x), recip(x), sq(x), sqrt(x), a + b (add), a / b (divide), a ^ b (exponent), a * b (multiply), and a - b (subtract).


Power Curve Regression

An object used to fit a power curve to (x,y) data.

Use

Use the power regression to fit the data to the equation y = C0 * x^C1, where x is the x coordinate and C0 and C1 are calculated coefficients.

The power curve regression object expects an array of Coord type of input with one independent variable. That is, an (x,y) pair. If the input array is not a Coord type an attempt is made to convert it to Coord. If the input data is mapped (Waveform, Spectrum, or a mapped array), then the conversion to Coord uses the mapping information to create the x part of the (x,y) pairs. If the input data is not mapped (for example, an array), then the x part of the (x,y) pair is implicitly generated from its position in the array.

Open View Parameters

The Fit Type field on the open view is used to change the regression type to linear, logarithmic, exponential, power curve or polynomial regression. Clicking on the field will bring up a list of the different regression types.

Example

See Regression for a Coord conversion example.

Notes

See Regression for general notes on regression.

This function will not work for unmapped arrays. Unmapped arrays are converted to Coord starting with x=0, which fails in the conversion in the log function. The log function is used in the internal regression calculation.

Location

Device [image] Regression

then select the appropriate Fit Type from the Fit Type field on the dialog box.

See Also

Regression, exponential regression, linear regression, logarithmic regression, meanSmooth (x,numPts), movingAvg (x,numPts), polynomial regression, polySmooth (x), and Build Coord.


Probability & Statistics

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use the Probability & Statistics functions in problems dealing with random numbers, probabilities and statistical calculation.

beta(x,y)

binomial(a,b)

comb(n,r)

erf(x)

erfc(x)

factorial(n)

gamma(x)

logMagDist(x,from,thru,logStep)

magDist(x,from,thru,step)

max(x)

mean(x)

median(x)

min(x)

mode(x)

perm(n,r)

random(low,high)

randomize(x,low,high)

randomSeed(seed)

rms(x)

sdev(x)

vari(x)

Location

Device [image] Function & Object Browser [image] Built-in Functions [image] Probability & Statistics

See Also

beta(x,y), binomial(a,b), comb(n,r), erf(x), erfc(x), factorial(n), gamma(x), logMagDist (x,from,thru, logStep), magDist(x, from,thru, step), max(x), mean(x), median(x), min(x), mode(x), perm(n,r), random (low,high), randomize (x,low,high), randomSeed (seed), rms(x), sdev(x), and vari(x)


product(x)

An object used to multiply all the elements of the input array.

Use

Use product(x) to multiply together all the elements of the input array. The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Real64 scalar
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | PComplex Scalar

The output of this object is the arithmetic product of all the data contained in the input container and is Scalar in shape.

Example

Where x is an array [1, 2, 3, 4], product(x) returns 24.

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Array
> product

See Also

a * b (multiply) and sum(x).


programName()

An object that returns the name of the VEE program currently executing.

Use

Returns the complete path, including the name, of the VEE program currently executing. This function takes no parameters.

Notes

The programName() object is simply a Formula object initialized without inputs and containing the programName() equation. You may also type programName() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> System Information
> programName

See Also

installDir, commandLine, Formula


ramp (numElem, from,thru)

An object that generates a linearly ramped array.

Use

Use ramp(numElem,from,thru) to generate a Real64 one-dimensional array of length numElem, with the values linearly ramped from from to thru (inclusive). numElem must be a scalar container that is, or can be converted to Int64 and with a value greater than zero. from and thru must be scalar containers that are, or can be converted to, Real64.

If from is less than thru, the ramping is positive; otherwise it automatically ramps negatively.

Example

ramp(3, 0.5, 0) returns a one-dimensional array with values [0.5, 0.25, 0].

ramp(5, 2, 10) returns a one-dimensional array with values [2, 4, 6, 8, 10].

Notes

The return value has no mappings.

The algorithm for generating values is:

Y[I] = from + I*(thru-from/numElem-1)
for I=0..numElem-1

This has the effect that the last element in the resultant array has the value thru.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Generate
> ramp

See Also

Alloc Real64, logRamp (numElem, from,thru), and xramp (numElem, from,thru).


random (low,high)

An object used to generate random numbers between a low and high value. This function generates pseudo-random numbers using the linear congruential algorithm and 48-bit integer arithmetic.

Use

Use random(low,high) to generate pseudo-random numbers between the low and high value. The numbers generated are in the interval including the low value, but not including the high value, which is denoted as "[l h)". The l and h inputs must be Scalar in shape.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64

A Real64 Scalar is returned in all cases that are in the range of "[l h)".

This function only outputs a single Scalar value. Use the randomize(x,low,high) function with an array input to generate an array of scaled random numbers.

If the l value is greater than the h value, then the range of random numbers returned is in the interval "(l h]".

Example

random(0,1) will generate real numbers in the range (0.0 1.0). That is, including 0.0, but excluding 1.0.

Notes

random(low,high) will return a Real Scalar container in the range "(0.0 1.0)".

Also, random(low,high) will return a different number each time it is used in a program or if it is activated several times by an iterator object.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> random

See Also

randomize (x,low,high) and randomSeed (seed)


randomize (x,low,high)

An object used to randomize the values of a numeric input container in the range of [low high). The numbers generated are in the interval including low, but not including high, which is denoted as "[low high)". This function generates pseudo-random numbers using the linear congruential algorithm and 48-bit integer arithmetic.

This object can also be used to randomize strings in Text input containers within the range of [low high].

Use

For numeric values:

Use randomize(x,low,high) to generate pseudo-random numbers between low and high, that is, between the low and high value. All of the data in the input container, x is overwritten with the pseudo-random numbers. The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord, see following
Waveform | Waveform
Complex | Complex
PComplex | PComplex, see following
Spectrum | Spectrum, see following

For PComplex and Spectrum types, only the magnitude of the number is in the range [low high). The phase is random in the range (-PI to PI). For type Coord, only the dependent variable is randomized.

The low and high inputs must be Scalar in shape and of a type that can be converted to the type of x. The random numbers generated are in the range of [low high).

If the low value is greater than the high value, then the range of random numbers returned is in the interval (low high].

For string values:

To randomize a string, use randomize(x,low,high) with input values of the Text data type. The input string (the data container on the x input) will be overwritten by an output string of ASCII characters in pseudo-random order, within the range [low high], where low is the first character in the low input container and high is the first character in the high input container. (Note that the range is inclusive of both low and high, which is different than for numeric values.) The length of the output string is the same as that of the input string.

The default values for low and high are the space (" ", ASCII 32) and the tilde ("~", ASCII 126).

Note
Default values are used for strings when the input data for low or high is "" (null string).

Examples

Numeric example:

If the container on the x input is of the Real64 data type, randomize(x,0,10) will randomize all the values of the input container x to real numbers in the range (0.0 10.0). That is, including 0.0, but excluding 10.0.

String examples:

randomize("abcdef","a","b") might return "abbaba".

randomize("abcabcabcab","a","z") might return "pterodactyl". (Well -- it might!)

randomize("abcabc","","") might return "Al@z~#". (With null strings for low and high, the default limits -- ASCII 32 through 126 -- are used.)

randomize("aaaaa","go","stop") might return "smjpg". (Only the first characters in low and high count in determining the range.)

randomize("aaaaa","97","99") returns "99999". (The low and high values are interpreted as strings, not ASCII decimal values.)

Notes

Mappings on input parameters are ignored and the output has the same mappings as the input parameter x.

For a numeric x input, randomize(x) will return a container the same size and shape as x, but with the data randomized in the range (0.0 - 1.0).

For string operations, the character set for output cannot be defined outside the limits low = ASCII 32 and high = ASCII 126. That is, the ASCII characters below 32 and above 126 are not allowed for output in the randomized string.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> randomize

See Also

random (low,high) and randomSeed (seed).


randomSeed (seed)

An object used to set initial values for the random(low,high) and the randomize(x,low,high) functions.

Use

Use randomSeed(s) to input a random seed entry point for the linear congruential algorithm used by the random(low,high) and the randomize(x,low,high) functions.

The seed input s must be Scalar in shape and of the type Int32 or of a type able to be converted to Int32. The return value of this function is the s seed value.

Example

randomSeed(97) initializes the pseudo-random number algorithm.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> randomSeed

See Also

random (low,high) and randomize (x,low,high).


re(x)

An object that returns the real part of a Complex number x.

Use

Use re(x) to extract the real part of a Complex number x. x can be any shape.

Allowed Input Type Return Type

UInt8 | UInt8, with same value
UInt16 | UInt16, with same value
Int16 | Int16, with same value
Int32 | Int32, with same value
Int64 | Int64, with same value
Real32 | Real32, with same value
Real64 | Real64, with same value
Coord | Coord, with same value
Waveform | Waveform, with same value
Complex | Real64, value of the real part of the Complex number
PComplex | Real64, value of the real part of the Complex number
Spectrum | Real64, value of the real part of the Complex number

PComplex is first converted to Complex.

Example

re( (1,2) ) returns 1.

re(1,@180), with Trig Mode in Degrees, returns -1.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Complex Parts
> re

See Also

Complex Parts, conj(x), im(x), j(x), mag(x), phase(x), and Real Parts.

Build Complex and UnBuild Complex.


Real Parts

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Real Parts to access the following objects which return different real parts of a container.

abs(x)

signof(x)

ordinal(x)

round(x)

floor(x)

ceil(x)

intPart(x)

fracPart(x)

Location

Device [image] Function & Object Browser [image] Built-in Functions [image]  Real Parts

See Also

abs(x), ceil(x), floor(x), fracPart(x), intPart(x), ordinal(x), round(x), signof(x), and Complex Parts.


recip(x)

An object that returns the reciprocal of the value of x.

Use

Use recip(x) to generate the reciprocal of a number; that is, one divided by the number x. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

For PComplex, the recip(x) is defined as the reciprocal of the magnitude, and the phase's sign is reversed. Complex is converted to PComplex before the function is applied.

Example

recip( (5, @45) ) returns (0.2, @-45).

recip( (1,-1)) ) returns (0.5, 0.5).

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> recip

See Also

a / b (divide), Power, sq(x), and sqrt(x).


rect(x)

An object used to apply a rectangular window to a time series of values.

Use

Use rect(x) to filter the values in x in the same manner as convolving x with the spectral transform of the rectangular function. This has the effect of suppressing some of the noise due to the tails of the input sequence and the potential discontinuities they represent when sampling periodic signals. The input x must be an Array 1D.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Spectrum | Spectrum

If x is a Spectrum, it is first converted to a Waveform using an ifft(x) before the window is applied. The result of the window is then converted back to type Spectrum using an fft(x).

Example

rect([1, 1, 1, 1, 1, 1, 1, 1]) returns [1, 1, 1, 1, 1, 1, 1, 1].

Notes

The rect function is represented in the time domain as 1 for all values, where
0 <= n <= N -1, where n is the position (index) in the array, and N is the size of the array. The result will be an array of the same type as x and will have the same mappings as x (if any).

For a discussion of sidelobe levels and coherent gains, see: Ziemer, Tranter, and Fannin, Signals and Systems, Macmillan Publishing, New York, NY, 1983. ISBN #0-02-431650-4.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> rect

See Also

bartlet(x), blackman(x), convolve(a,b), fft(x), hamming(x), and hanning(x).


Regression

A menu item.

Use

Use Regression to fit various types of regression equations to data.

linear

logarithmic

exponential

power curve

polynomial

Notes

All the Regression objects expect an array of Coord type for input. If the input array is not a Coord type it is converted to Coord. The conversion to Coord type follows standard type conversion rules summarized here. If the input array is not mapped, then an implicit x parameter is generated from the array indices. That is, the regression must be done on (x,y) pairs. The x values will start at zero and range to n - 1, where n is the number of data points. If the input array is mapped then the generated x data will range from the low value of the mapping to the high value of the mapping.

The regression gives as output an array of data fitted to the equation chosen. The number of points of the output array is the same as in the input data array. It also outputs an array of coefficients that corresponds to the derived constants for each regression type. See the individual regression type to determine to which equation the data is fitted. The third output is the R-squared or "goodness of fit" coefficient. It ranges between -1 and 1. A fit of -1 or 1 is an exact fit and numbers in between -1 and 1 represent varying degrees of goodness of fit.

Example

You have an unmapped array input [10, 20, 30, 40, 50]. It would be converted to Coord array:

[ (0, 10), (1, 20), (2, 30), (3, 40), (4, 50) ].

If an input array is the array [1, 2, 3, 4, 5], and it is mapped from 1 to 2 (seconds for instance), it would be converted to Coord array:

[ (1, 1), (1.25, 2), (1.5, 3), (1.75, 4), (2, 5) ].

Location

Device [image] Regression

See Also

exponential regression, linear regression, logarithmic regression, polynomial regression, power curve regression, meanSmooth (x,numPts), movingAvg (x,numPts), and polySmooth (x).

Properties (Object)


rms(x)

An object used to return the rms (Root Mean Square) value of the data in the input container.

Use

Use rms(x) to calculate the Root Mean Square value of the input container. The rms value is defined as the square root of [(The sum of x^2)/N], where N is the number of the points. The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | Real64 Scalar
UInt16 | Real64 Scalar
Int16 | Real64 Scalar
Int32 | Real64 Scalar
Int64 | Real64 Scalar
Real32 | Real64 Scalar
Real64 | Real64 Scalar
Coord | Real64 Scalar
Waveform | Waveform

For Coord input types, the operation is done on the dependent variable.

Example

Where x is the array [1, 2, 3, 4, 5, 11, 12, 13, 14, 34], rms(x) returns 13.319159.

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> rms

See Also

max(x), mean(x), median(x), min(x), mode(x), sdev(x), and vari(x).


rotate(x, numElem)

An object used to rotate elements in an array.

Use

Use rotate(x,n) to rotate the elements of the input array x by n positions. The x input may be of any size and shape.

Allowed x Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum
Text | Text

The input n must be a scalar Int32 or be able to be converted to Int32 type. If the n rotate value is a positive value, the rotation direction is down the array (forward). For example, if n was 2, then the first element of the array would end up in the third position (x[2]) , the second element ends up in the fourth position (x[3]), and so on. If the n value is negative, the array elements are rotated up the array (backward).

If the rotate number n is larger than the number of elements in the array, then the number of places to rotate is calculated by taking the modulo of the rotate number by the number of array elements. For example, if the input array has 5 elements and you want to rotate the array 13 places, the modulo operation (13 MOD 5 = 3) determines that the array should be rotated 3 places.

Example

rotate(x,5) rotates the input array elements 5 positions further to the right in the array.

rotate(x,15), where the input array x has 15 elements, does nothing because you have rotated the array back on top of itself.

rotate([1, 2, 3, 4, 5], 1) returns [5, 1, 2, 3, 4].

Notes

You might think of the array as a circular list when using the rotate function, meaning that the last element in the array is connected to the first array element. When you rotate array elements past the end of the array, they wrap back around to the top of the list. For example, if the array is 10 elements long and you do a rotate(A,5), then the tenth array element number will end up in fifth position in the array.

Mappings on input parameters are ignored and the output has the same mappings as the input parameter x.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Array
> rotate

See Also

concat(x,y) and init(x,val).


round(x)

An object that returns the rounded value of x.

Use

Use round(x) to obtain the rounded value, to the nearest integer, of a container. x may be any shape. The round(x) function returns the closest integer (as the same type) to x. The dividing line is at 0.5, which rounds up.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

round([23.0, 23.1, 23.9, 23.5, (-23.5)]) returns
[23, 23, 24, 24, -23].

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Real Parts
> round

See Also

abs(x), ceil(x), Complex Parts, floor(x), fracPart(x), intPart(x), and Real Parts.


savePanelImage(UFName, fileName, numColors)

Saves the panel image of the UserFunction named UFName to the file fileName using a pixel depth of numColors.

Use

Use savePanelImage(UFName, fileName, numColors) to programmatically render a VEE UserFunction panel to a standard graphics file. This lets you refer to a VEE UserFunction panel in a report. UserObject panels are not supported in the savePanelImage function.

When running a program repeatedly, the graphics file will be overwritten without notifying you, unless you change fileName.

Open View

The function includes three parameters; only UFName is required:

"UFName" - (required) The name in the UserFunction title bar. You can also use the special name "Execution Window" (entered exactly as shown here) in place of "UFName". Double-quotes must surround this name.

"fileName" (optional) The target file name for the rendered image, which can include a destination drive and directory. Double-quotes must surround this name. The default file name uses UFName’s base name. If UFName is Execution Window, the default file name will be Execution. The default destination is the VEE default working directory, which is "C:\My Documents" in the standard VEE installation.

The file name extension for fileName determines the output file’s graphics format. The default graphics format is JPEG. Supported formats are

.bmp - Bitmap

.jpg/.jpeg - Joint Photographic Experts Group (JPEG)

numColors (optional) The color-depth, specifying the maximum number of colors per pixel. This number is a power of two (2, 4, 8, ... 2M). The default is 256.

Note
numColors applies only to Bitmap graphics files (.bmp). Specifying a smaller number will reduce the resulting file size, and will degrade the image clarity.

Examples

The following example renders an image of the local UserFunction named my_userfunc, writing a file using the defaults for the optional parameters. The file is saved as my_userfunc.jpeg, in VEE's current working directory.

savePanelImage("my_userfunc")

The following example is similar to the previous one, except the expressions will save the Execution Window in its current state.

savePanelImage("Execution Window")

The following example renders an image of the local UserFunction named someUF, writing a file named myimage.jpeg in the destination d:\tmp\somedir using the JPEG format.

savePanelImage("someUF", "d:/tmp/somedir/myimage.jpeg")

The following example renders an image of the local UserFunction named someUF, writing a file named myimage.bmp in the destination d:\tmp\somedir using the BMP format. It writes the file using 16 colors per pixel instead of the default 256.

savePanelImage("someUF", "d:/tmp/somedir/myimage.bmp", 16)

The following example renders an image of the imported UserFunction named statusPanel, which is located in the library lib1. It writes a file named status.jpeg using the JPEG format in the directory /usr/lib/veepanels.

savePanelImage("lib1.statusPanel", "/usr/lib/veepanels/status.jpeg")

Notes

The savePanelImage() function is created in a Formula object that is preconfigured with a data input for each of the three parameters. You can enter a savePanelImage() function call in any other Formula object.

You can enter the entire expression programmatically by adding the control input named Formula.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Panel
> savePanelImage

See Also

Call, Execution Window, hidePanel(), showPanel(), and UserFunction.


sdev(x)

An object used to return the standard deviation of the data in the input container.

Use

Use sdev(x) to calculate the standard deviation of the container. sdev(x) is defined as the square root of the vari(x). The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | Real64 Scalar
UInt16 | Real64 Scalar
Int16 | Real64 Scalar
Int32 | Real64 Scalar
Int64 | Real64 Scalar
Real32 | Real32 Scalar
Real64 | Real64 Scalar
Coord | Real64 Scalar
Waveform | Real64 Scalar

For Coord input types, the operation is done on the dependent variable.

Example

Where x is the array [1, 2, 3, 4, 5, 11, 12, 13, 14, 34], sdev(x) returns 9.50789.

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> sdev

See Also

max(x), mean(x), median(x), min(x), mode(x), rms(x), and vari(x).


setBit(x,n)

An object that returns x with the nth bit set to 1.

Use

Use setBit(x,n) to set a particular binary digit of a container x to 1. x can be any shape. If x is of type Real32, Real64, Coord or Waveform, it is converted to Int32 before the operation.

Allowed Input Type |  | Return Type
x | n
UInt8 | 0-31 | UInt8
UInt16 |  | UInt16
Int16 |  | Int16
Int32 |  | Int32
Int64 | 0-63 | Int64
Real32 | 0-31 | Int32
Real64 |  | Int32
Coord |  | Int32
Waveform |  | Int32

n must be a container which is, or can be converted to, Int32 and have a value between 0 and 31 inclusive (between 0 and 63 inclusive when x is of type Int64). n must be either scalar or match the shape of x.

Example

setBit(8,0) returns 9.

setBit(8.24,0.9) also returns 9.

Notes

The mappings of the return value are the same as the x parameter.

The least significant bit is on the right, and the most significant bit is on the left.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bitwise
> setBit

See Also

bit(x,n), bits(str), Bitwise, and clearBit(x,n).


showPanel()

An object that displays a UserFunction panel.

Use

Use showPanel() to display a UserFunction
 panel until hidePanel() is executed or
 the program finishes running. showPanel()
 allows you to have a status panel up for as long as you need it. To use
 showPanel(), Show
 Panel on Execute must not be selected on the UserFunction.

Open View

The three versions of showPanel() objects exist to show you the syntax to use. You must include the text showPanel() in the edit field. Inside the parenthesis, you can type the following parameters in any of the objects:

"UFname" - The name of the UserFunction. You must have double quotes around this name. This parameter is required.

x, y - The location (in pixels) for the upper-left corner of the UserFunction panel (including the area for the border and title bar if they exist). This parameter is optional; if you do not specify the x and y coordinates, the panel is displayed in the center of the work area.

width, height - The size of the panel (in pixels). This parameter is optional; if you specify width and height, you must specify the x, y parameters. If you do not specify width and height, the current panel size is used. width and height settings add and delete space from the right and lower sides of the panel view and include the title bar and border if they exist.

You may add data input pins to the showPanel() object to set any of the parameters if you replace the parameter with the input terminal name.

Notes

showPanel() does not run the UserFunction, it only displays the Panel View. To see the panel and run the UserFunction, first use showPanel() and then call the UserFunction.

If you only want to see the Panel View when the UserFunction operates, select Show Panel on Execute from the UserFunction Properties window instead of using showPanel().

The showPanel() object is simply a Formula object initialized without inputs and containing the showPanel(...) equation. You may also type showPanel() (and the associated parameters) into any objects that allow expressions, such as the Formula and Sequencer objects.

You may input the entire showPanel() equation via control pin.

VEE does not limit the location of the pop-up panel to the size of your work area, it is possible to specify an x and y that are "off screen" (out of the visible window).

All panels shown with showPanel() are only shown while the program is running.

You can have only one copy of a UserFunction panel showing at a time. If you call showPanel() additional times with the same UserFunction name, the latest call of the panel is shown and the previous is hidden.

To find the name of a panel that is showing, click the right mouse button on the panel and the panel name pops up.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Panel
> showPanel

See Also

Call, hidePanel(),
 lockPosition(), panelPosition(),
 panelSize(), unlockPosition(),
 and UserFunction.


Signal Processing

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Signal Processing to access one of several signal processing functions that can be applied to one-dimensional arrays (UInt8, UInt16, Int16,Int32,Int64, Real32, Real64, Complex, PComplex, Waveform, Spectrum) for some functions, and lists of two-dimensional (two field) coordinates.

fft(x)

ifft(x)

convolve(a,b)

xcorrelate(a,b)

bartlet(x)

hamming(x)

hanning(x)

blackman(x)

rect(x)

Notes

The Built-in Functions under Signal Processing are applicable to one-dimensional arrays of values that represent ordered, equally spaced data.

Location

Device [image] Function & Object Browser [image] Built-in Functions [image] Signal Processing

See Also

bartlet(x), blackman(x), convolve(a,b), fft(x), hamming(x), hanning(x), ifft(x), rect(x), and xcorrelate (a,b).


signof(x)

An object that returns the sign of x.

Use

Use signof(x) to obtain the sign of a container. x may be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Int32
Real64 | Int32
Coord | Int32
Waveform | Int32

The return will have a value of -1, 0, or +1, depending on whether the x value is negative, zero, or positive. If x is negative, -1 is returned; if x is zero, 0 is returned; if x is positive then +1 is returned.

Example

signof([23, 0, -1]) returns [1, 0, -1].

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Real Parts
> signof

See Also

abs(x), Complex Parts, and mag(x).


sin(x)

An object that returns the sine of x.

Use

Use sin(x) to generate the sine of the x data. x is assumed to be in the current Trig Mode units. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

sin([0, PI/2]) returns [0, 1] with Trig Mode set to Radians.

sin((1, @PI)) returns (0.84147, @3.14159) with Trig Mode set to Radians.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> sin

See Also

asin(x), cos(x), tan(x), sinh(x), Trig, and Default Preferences.


sinh(x)

An object that returns the hyperbolic sine of x.

Use

Use sinh(x) to generate the hyperbolic sine of the x data. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

sinh(1.2) returns 1.509.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> sinh

See Also

asinh(x), cosh(x), Trig, sin(x), and tanh(x).


sort(x, direction, field)

A function that sorts an array of data (any data type).

Use

Use the sort function in a Formula object to sort an array of data on input x. All data types are allowed, and by default the data is sorted in ascending order. If you use sort in a Formula object the syntax is:

sort(x [,direction [,field] ] )

where:

direction (optional) specifies the direction of sort. The default is ascending order, and any non-zero value will specify ascending order. A value of 0 specifies a sort in descending order.

field (optional) specifies the field on which to sort the array:

For the real, integer, and Text data types, this parameter is ignored.

For the Complex data type, specify 0 or "real" to sort on the real field. Specify 1 or "imag" to sort on the imaginary field. All three parameters must be specified.

For the PComplex data type, specify 0 or "mag" to sort on the magnitude field. Specify 1 or "phase" to sort on the phase field. All three parameters must be specified.

For the Coordinate data type, the array will be sorted by the dependent field by default ("y" in an x-y pair, "z" in an x-y-z triplet). Specify 0 or "x" to sort on the x field, 1 or "y" to sort on the y field, and so forth. (Note that for the Coordinate data type, the field names will always be x, y, z, w, v, u, t, s, r, q even though you may change the input terminal names.)

For the Record data type, the array will be sorted by the first field by default. Or you can specify the field by number (0, 1, and so forth) or by name ("operator", "date", etc.).

Examples

sort(x) will sort a real array x in ascending order.

sort(x,0) will sort a real array x in descending order.

sort(x,1,"real") or sort(x,1,0) will sort a Complex array x by the real field in ascending order.

sort(x,0,"phase") or sort(x,0,1) will sort a PComplex array x by the phase field in descending order.

sort(x,1,"A") or sort(x,1,0) will sort a Coordinate array x by the "A" field in ascending order.

sort(x,1,1) will sort a Record array x by the second field in ascending order.

Notes

Text data is sorted by the standard ASCII character-code order. Thus, uppercase letters come before lowercase letters.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Array
> sort

See Also

Formula.


sq(x)

An object that returns the square of the value of x.

Use

Use sq(x) to perform the squaring of a number x (multiplies the value of x times itself). x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

sq([1, 4]) returns [1, 16].

sq((1,2)) returns the complex number (-3,4).

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> sq

See Also

Power and sqrt(x).


sqrt(x)

An object that returns the square root of the value of x.

Use

Use sqrt(x) to generate the square root of a number x. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

For PComplex, the sqrt(x) is defined as the square root of the magnitude and half the phase. Complex is converted to PComplex before the function is applied.

Example

sqrt( (16, @90) ) will return (4, @45).

sqrt( (1,1) ) will return (1.1, 0.455).

sqrt([4, 9, 64]) will return [2, 3, 8].

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Power
> sqrt

See Also

cubert(x), a ^ b (exponent), Power, and sq(x).


Statistics

See Probability & Statistics.


strDown(str)

An object that changes all uppercase alphabetic characters in a string to lowercase characters.

Use

Use strDown(str) to change the case of an input string str to lowercase. All uppercase alphabetic characters ("A" through "Z") are converted to the corresponding lowercase characters ("a" through "z"). Non-alphabetic ASCII characters are left unchanged.

Examples

strDown("ABCdefg%+#") returns "abcdefg%+#"

strDown("123456") returns "123456"

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strDown

See Also

strRev(str), strTrim (str,trimlist), strUp(str), and String.


strFromLen (str,from,len)

An object that returns a substring of a specified length and starting point.

Use

Use strFromLen(str,from,len) to return a substring from the input string str, beginning at index position from and of length len in bytes. If from = 0, the substring starts at the beginning of the input string. Base 0 indexing of the string is used.

Notes

If the value of len is less than or equal to 0, a nil string will be returned.

If the value of from is greater than the length of the input string str, a nil string will be returned.

If the value of len is greater than the length of the input string str, the returned string stops at the end of the input string.

If the input string is an array of strings, each element of the input array is operated on as a separate string. The return value is a string array.

Examples

strFromLen("Now is the time",0,6) returns "Now is"

strFromLen("Now is the time",6,9) returns " the time"

strFromLen("Now is the time",0,30) returns "Now is the time"

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strFromLen

See Also

strFromThru (str,from, thru), strPosChar (str,char), strPosStr (str1,str2), and String.


strFromThru (str,from, thru)

An object that returns a substring of a specified starting point and ending point.

Use

Use strFromThru(str,from,thru) to return a substring from the input string str, beginning at index position from and ending at index position thru. If from = 0, the substring starts at the beginning of the input string. Base 0 indexing of the string is used.

Notes

Negative values of from or thru are converted to 0.

Values of from or thru that are greater than the length of the input string str are converted to the index position of the last character in the input string.

If the value of from is greater than the length of the input string str, or greater than thru, a nil string is returned.

If the input string is an array of strings, each element of the input array is operated on as a separate string. The return value is a string array.

Examples

strFromThru("Now is the time",0,6) returns "Now is "

strFromThru("Now is the time",0,0) returns "N"

strFromThru("Now is the time",6,9) returns " the"

strFromThru("Now is the time",0,30) returns "Now is the time"

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strFromThru

See Also

strFromLen (str,from,len), strPosChar (str,char), strPosStr (str1,str2), and String.


String

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use the String functions to perform these operations on string data:

strDown(str)

strFromLen(str,from,len)

strFromThru(str,from,thru)

strLen(str)

strPosChar(str,char)

strPosStr(str1,str2)

strRev(str)

strTrim(str)

strUp(str)

intToChar(a)

charToInt(a)

Notes

All of the string functions are capable of operating on inputs that are string arrays. The results will be a text or number array. Operations are done on each individual element of the input string array.

Location

Device [image] Function & Object Browser [image] Built-in Functions [image] String

See Also

charToInt(a), intToChar(a), strDown(str), strFromLen (str,from,len), strFromThru (str,from, thru), strLen(str), strPosChar (str,char), strPosStr (str1,str2), strRev(str), strTrim (str,trimlist), and strUp(str).


strLen(str)

An object used to determine the length of a string in bytes.

Use

Use strLen(str) to determine the length of an input string str. The return value is an Int32 Scalar giving the number of bytes present. Kanji characters and other 16-bit characters count as two bytes each.

Notes

If the input string is an array, the length of each element will be returned in an output array.

Examples

strLen("ABCdefg%+#") returns 10

strLen("123456") returns 6

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strLen

See Also

String.


strPosChar (str,char)

An object that returns the index within the input string str of any character in the character list char.

Use

Use strPosChar(str,char) to return the index within the input string str of the first occurrence of any character in character list char. Base 0 indexing of the string is used.

Notes

If there is more than one occurrence of more than one listed character, only the index of the first listed character found is returned.

If none of the characters listed in char are found in the input string str, a value of -1 is returned.

If either str or char is the nil string, a value of -1 is returned.

Note that the character match is case sensitive.

If the input string is an array, each element of the array is searched as a separate string. The positions of characters in the string elements are put in an output array.

Examples

strPosChar("Now is the time","Nwme") returns 0

strPosChar("Now is the time","nwme") returns 2

strPosChar("Now is the time","x yz ") returns 3

strPosChar("Now is the time","") returns -1

strPosChar("Now is the time","xyz") returns -1

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strPosChar

See Also

strFromLen (str,from,len), strFromThru (str,from, thru), strPosStr (str1,str2), and String.


strPosStr (str1,str2)

An object that returns the index of string str2 within string str1.

Use

Use strPosStr(str1,str2) to return the index of the first occurrence of string str2 within string str1 -- that is, the index position within str1 where str2 begins. Base 0 indexing is used.

Notes

If str2 occurs more than once in str1, only the index of the first occurrence is returned.

If an occurrence of str2 is not found within str1, a value of -1 is returned.

If either str1 or str2 is the nil string, a value of -1 is returned.

Note that the character match is case sensitive.

If the input string is an array, each element of the array is searched as a separate string. The positions of strings in the string elements are put in an output array.

Examples

strPosStr("Now is the time","Now") returns 0

strPosStr("Now is the time","is the") returns 4

strPosStr("Now is the time","") returns -1

strPosStr("Now is the time","is The") returns -1

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strPosStr

See Also

strFromLen (str,from,len), strFromThru (str,from, thru), strPosChar (str,char), and String.


strRev(str)

An object used to reverse the order of a string.

Use

Use strRev(str) to reverse the order in which the characters in a string appear.

Notes

If the input string is an array, the return value is a string array with each element reversed.

Examples

strRev("ABCdefg%+#") returns "#+%gfedCBA"

strRev("123456") returns "654321"

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strRev

See Also

strDown(str), strTrim (str,trimlist), strUp(str), and String.


strTrim (str,trimlist)

An object used to trim spaces and tab characters from the front and back of a string.

Use

Use the strTrim(str) object to trim leading and trailing spaces and tab characters from an input string str. All spaces and tab characters that precede the first non-space/non-tab character, or follow the last non-space/non-tab character, are trimmed. In a Formula object the complete syntax is:

strTrim(str [,trimlist] )

Use strTrim(str,trimlist) to trim off any characters from str that are contained in trimlist. Note that these characters are trimmed only if they are leading or trailing characters in str.

Notes

You can extend the syntax of this function to strTrim(str,trimlist) by using it in a Formula object with two inputs: str and trimlist. In this case, any characters listed in the trimlist string, if leading or trailing, are trimmed from the str input string.

If the input string is an array, the return value is a string array with each element trimmed.

Examples

strTrim(" ABCdefg%+#") returns "ABCdefg%+#"

strTrim("eeeABCdefg%+#","eg#") returns "ABCdefg%+"

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strTrim

See Also

strDown(str), strRev(str), strUp(str), and String.


strUp(str)

An object used to change all lowercase alphabetic characters in a string to uppercase characters.

Use

Use strUp(str) to change the case of an input string str to uppercase. All lowercase alphabetic characters ("a" through "z") are converted to the corresponding uppercase characters ("A" through "Z"). Non-alphabetic ASCII characters are left unchanged.

Notes

If the input string is an array, the return value is a string array with each element treated as a separate string.

Examples

strUp("ABCdefg%+#") returns "ABCDEFG%+#"

strUp("123456") returns "123456"

Location

Device [image] Function & Object Browser

>  Built-in Functions
> String
> strUp

See Also

strDown(str), strRev(str), strTrim (str,trimlist), and String.


a - b (subtract)

An object that performs an arithmetic subtraction on two operands.

Use

Use a - b to subtract the value of one container from another container. The two containers may be any shape, and the same shape is returned. The result is a container of the highest type with the same shape as the operands.

Allowed Input Type Return Type

UInt8

Highest type

of

the two operands

UInt16

Int16

Int32

Int64

Real32

Real64

Coord

Waveform

PComplex

Spectrum

If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is a container of the highest type.

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. The subtraction is only performed on the dependent (last) variable.

Example

Array minus a scalar: [1, 2, 3] - 3 returns [-2, -1, 0].

Scalar minus an array: 3 - [1, 2, 3] returns [2, 1, 0].

Two arrays: [4, 5, 6] - [3, 2, 1] returns [1, 3, 5].

Two Complex scalars: (2,4) - (1,3) returns (1,1).

Two Coord scalars: coord(1,3) - coord(1,5) returns coord(1,-2).

Two Coord scalars: coord(1,3) - coord(2,5) returns an error.

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Location

Device [image] Function & Object Browser

>  Operators
> Arithmetic
> -

See Also

a + b (add), a / b (divide), and a * b (multiply).


sum(x)

An object used to sum up (add) all the elements of the input array.

Use

Use sum(x) to add together all the elements of the input array. The x input may be of any size and shape.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Coord | Real64 Scalar
Waveform | Real64 Scalar
Complex | Complex
PComplex | PComplex
Spectrum | PComplex
Text | Text Scalar

The output of this object (for numeric types) is the arithmetic sum of all the data contained in the input container and is a Scalar. For Text type input, the output is a Scalar Text container and contains the concatenation of all of the Text elements together to form one large string.

The sum(x) object obeys the same rules for Text string addition as the dyadic operator +.

Example

Where x is an array [1, 2, 3, 4], sum(x) returns 10.

Where x is an array ["first", "second", "third"], sum(x) returns "firstsecondthird".

Notes

Mappings on the operand are ignored.

Note the difference between the concat(x,y) and sum(x) functions on text inputs. The concat(x,y) creates an Array 1D in all cases. The sum(x) function will simply link all the text strings together to form one large output string. That is, concat(x,y), where x is the Scalar Text value "a" and y is the Scalar Text value "b", yields the Array 1D ["a","b"]. On the other hand, sum(["a","b"]) will return the Scalar container with the Text value of "ab" in it.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Array
> sum

See Also

a + b (add), concat(x,y), and product(x).


tan(x)

An object that returns the tangent of x.

Use

Use tan(x) to generate the tangent of the x data. x can be any shape and the same shape is returned. x is assumed to be in the current Trig Mode units.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

tan([0, 45]) returns [0, 1] with Trig Mode set to Degrees.

tan((1, 2)) returns (33.8128m, 1.01479) with Trig Mode set to Radians.

tan((3, @PI/2)) returns (0.99505, @1.57079) with Trig Mode set to Radians.

Notes

Mappings are retained in the result. Using Trig Mode set to anything except Radians may result in accuracy errors beyond the 12th significant digit.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> tan

See Also

atan(x), atan2(y,x), cos(x), cot(x), sin(x), tanh(x), Trig, and Default Preferences.


tanh(x)

An object that returns the hyperbolic tangent of x.

Use

Use tanh(x) to generate the hyperbolic tangent of the x data. x can be any shape and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform
Complex | Complex
PComplex | PComplex
Spectrum | Spectrum

Example

tanh(0.6) returns 0.537.

Notes

Mappings are retained in the result.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Trig
> tanh

See Also

atanh(x), cosh(x), Trig, sinh(x), and tan(x).


Time & Date

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Time & Date to access the following objects which perform date and time conversions.

now()

wday(aDate)

mday(aDate)

month(aDate)

year(aDate)

dmyToDate(d,m,y)

hmsToSec(h,m,s)

hmsToHour(h,m,s)

Notes

The now() and dmyToDate(d,m,y) functions will output a time as the number of seconds since the beginning of the Epoch (00:00 hours 1 January 0001 AD) and is stored in UTC (Universal Coordinated Time). That is, a correction is applied for the time zone difference between your local time and GMT (Greenwich Mean Time). Since the wday(), mday(), month(), and year() functions expect a UTC type of time as input (from the now(), dmyToDate,(), Time Stamp or Date Time constant), they will remove the correction before doing the calculation.

The hmsToSec(h,m,s) and hmsToHour(h,m,s) are only doing conversion to delta (elapsed) time and do not apply any UTC correction. You may notice that output from one of these functions displayed in an alpha display (in some Time format) is off by the number of hours between your time zone and UTC. You will need to display this information with the Delta Time: time selection on the alpha Time Stamp display on transactions.

Location

Device [image] Function & Object Browser [image] Built-in Functions [image]  Time & Date

See Also

dmyToDate (d,m,y), hmsToHour (h,m,s), hmsToSec (h,m,s), mday(aDate), month(aDate), now(), wday(aDate), year(aDate), and To String.


totSize(x)

An object that returns an Int32 value that is the total size of a container.

Use

Use the totSize(x) function in a Formula object to determine the size of the container on input x. If x is a scalar or an array with one element, totSize(x) will return a value of 1.

Examples

For x= scalar: totSize(x) returns 1.

For x= [1]: totSize(x) returns 1.

For x= [1, 2]: totSize(x) returns 2.

For x= [ [1, 2] ,[3 ,4] ]: totSize(x) returns 4.

Notes

The totSize(x) function performs the same function as the TotSize pin in the Get Values object.

This object does not accept zero-element arrays.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Array
> totSize

See Also

Formula, and Get Values.


transpose(x)

An object used to calculate the transpose of a 2D array (a matrix).

Use

Use transpose(x) to return the transpose of a matrix. The x input must be any 2-Dimensional matrix. It does not have to be square.

Allowed Input Type Return Type

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real64
Complex | Complex
PComplex | PComplex
Text | Text

Examples

Where x is a square matrix [ [1, 2], [3, 4] ], transpose(x) returns
[ [1, 3], [2, 4] ].

Where x is a matrix [ [1, 2, 3], [4, 5, 6] ], transpose(x) returns
[ [1, 4], [2, 5], [3, 6] ].

Notes

Mappings on the operand are ignored and the output container has its mappings transposed.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Matrix
> transpose

See Also

det(x), identity(x), and inverse(x).


Triadic Operator

An operator that returns the result of one expression if a condition is true, but returns the result of another expression if that condition is false.

Use

Use the triadic operator in a Formula object with the following syntax:

(condition ? expression : expression)

If the condition is true, the result of the first expression is returned.

If the condition is false, the result of the second expression is returned.

The triadic operator must be used within a Formula object or other object that takes an expression.

Example

(A<10 ? A*2 : A*3) returns the result of A*2 if A<10 is true, but returns the result of A*3 if A<10 is false.

Notes

The enclosing parentheses are required.

The triadic operator is useful in setting up "IF/THEN/ELSE" conditional tests. The syntax is the same as for the C language triadic operator.

Location

Device [image] Function & Object Browser

>  Operators
> Miscellaneous
> (a ? b : c)

See Also

Comma Operator, Formula, If/Then/Else, and Miscellaneous Operators.


Trig

A Category of Built-in Functions on the Function & Object Browser tool window.

Use

Use Trig to access the following objects which perform trigonometric functions on data.

acos(x)

acosh(x)

acot(x)

acoth(x)

asin(x)

asinh(x)

atan(x)

atan2(y,x)

atanh(x)

cos(x)

cosh(x)

cot(x)

coth(x)

sin(x)

sinh(x)

tanh(x)

tan(x)

Notes

All Trig operations are performed in Radians. If Trig Mode is set to Degrees, all containers must be converted from Degrees to Radians before the function can be performed. Therefore, for the best performance, use Trig Mode set to Radians.

Location

Device [image] Function & Object Browser [image] Built-in Functions [image] Trig

See Also

acos(x), acosh(x), acot(x), acoth(x), asin(x), asinh(x), atan(x), atan2(y,x), atanh(x), cos(x), cosh(x), cot(x), coth(x), sin(x), sinh(x), tanh(x), tan(x), and Default Preferences.


typeName(x)

An object that returns the data type of x.

Use

Use typeName(x) to report the data type currently in a container. x may be of any size and shape. Returns one of the following names as Text:

VEE 6+ Mode All Other Modes

UInt8 | UInt8
UInt16 | UInt16
Int16 | Int16
Int32 | Int32
Int64 | Int64
Real32 | Real32
Real64 | Real
Complex | Complex
PComplex | PComplex
Text | Text
Enum | Enum
Coord | Coord
Waveform | Waveform
Spectrum | Spectrum
Record | Record
Object | Object

Example

Where x is a Complex array,
typeName(x) returns Complex.

Notes

If x is declared as a Variant, typeName(x) returns the data type of the contents of x. For example, if x is a Variant that currently contains an Int32, typeName(x) returns Int32.

Location

Location: Device [image] Function & Object Browser

> Built-in Functions
> Type Conversion

See Also

isVariant(x), isVariantBool(x), isVariantCurrency(x), isVariantDate(x), isVariantEmpty(x), isVariantError(x), isVariantNull(x).


unlockPosition()

An object that allows a user to move the UserFunction panel that is currently being shown.

Use

When you use showPanel() to display a UserFunction panel, and have used lockPosition() or have checked the PopupMoveable property to prevent the user from moving the panel, use unlockPosition() to allow the user to move the panel.

Open View

You must include the text unlockPosition(). Inside the parenthesis, you type the following parameter:

"UFname" - The name of the UserFunction. You must have double quotes around this name. This parameter is required.

You may add a data input pin to the unlockPosition() object to set the UserFunction name, but you must replace "UFname" with the input terminal name.

Notes

The unlockPosition() object is simply a Formula object initialized without inputs and containing the unlockPosition() equation. You may also type unlockPosition() into any other Formula object or expression.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Panel
> unlockPosition

See Also

Call, hidePanel(),
 lockPosition(), panelPosition(),
 panelSize(), showPanel(),
 and UserFunction.


vari(x)

An object that returns the variance of the data in the input container.

Use

Use vari(x) to calculate the variance of the data in the input container. x may be of any size and shape.

Allowed Input Type Return Type

UInt8 | Real64 Scalar
UInt16 | Real64 Scalar
Int16 | Real64 Scalar
Int32 | Real64 Scalar
Int64 | Real64 Scalar
Real32 | Real64 Scalar
Real64 | Real64 Scalar
Coord | Real64 Scalar
Waveform | Real64 Scalar

For Coord input types, the operation is done on the dependent variable.

The vari(x) is defined as:
[The SUM of (Xi - Xmean)^2] divided by (numPts - 1)
where Xi is the individual data point, Xmean is the mean of the data points, and numPts is the number of elements in the input array x.

Example

Where x is the array [1, 2, 3, 4, 5, 11, 12, 13, 14, 34],
vari(x) returns 90.4.

Notes

Mappings on the operand are ignored.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Probability & Statistics
> vari

See Also

max(x), mean(x), median(x), min(x), mode(x), rms(x), and sdev(x).


wday(aDate)

An object that returns the weekday of the time x.

Use

Use wday(aDate) to transform the given time x into a container of the same shape with value(s) 0 - 6, corresponding to the day of the week. The value 0 corresponds to Sunday, 1 to Monday, and so on, with 6 as Saturday. x may be any shape, and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

wday(dmyToDate(2,1,2003)) returns 4, so Jan 2, 2003 is a Thursday.

Notes

Mappings are retained in the return value.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> wday

See Also

dmyToDate (d,m,y), hmsToHour (h,m,s), hmsToSec (h,m,s), mday(aDate), month(aDate), now(), Time & Date, and year(aDate).


xcorrelate (a,b)

An object used to cross-correlate two arrays of data.

Use

Use xcorrelate(a,b) to calculate the discrete cross-correlation of two 1D arrays a and b. The result will be an array of the same type and of size (Na+Nb)-1, where Na is the size of input array a, and Nb is the size of input array b.

The input values a and b must be an Array 1D, and do not have to be the same size.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

The return type is the same as the highest type of the inputs. The resultant values are not normalized.

Example

xcorrelate([1, 2, 3, 4, 5],[3, 2, 1]) returns [1, 4, 10, 16, 22, 22, 15].

Notes

The inputs a and b must represent equally spaced data. In addition, the interval between any two values of a must be the same as that between any two values of b. For two unmapped arrays, it is assumed that the interval is always 1. For mapped arrays, the interval is (Xmax-Xmin)/N, where Xmax and Xmin are the mappings and N is the size of the array. When one input is mapped and the other is not, the unmapped input is assumed to be sampled at the same frequency as the mapped input. The resultant values will not be normalized.

Note that the xcorrelate(a,b) algorithm is essentially identical to the standard algorithm for discrete convolution, except that the second operand is not sequence-reversed as it is in convolution.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Signal Processing
> xcorrelate

See Also

convolve(a,b).


xlogRamp (numElem, from,thru)

An object that generates a logarithmically ramped array in the same manner used to generate x values for coordinate conversions of log mapped 1D Arrays.

Use

Use xlogRamp(numElem,from,thru) to generate a Real64 one-dimensional array of length numElem, with the values logarithmically ramped from from to thru. numElem must be a scalar container which is, or can be converted to, Int32 and with a value greater than zero. from and thru must be scalar containers which are, or can be converted to, Real64. If from is less than thru the ramping is positive; otherwise it automatically ramps negatively. Both from and thru must have values greater than zero.

Example

xlogRamp(3, 1, 100) returns a 1D Array with values [1, 10, 100].

Notes

The return value has no mappings.

The algorithm for generating values is:

Y[I]=exp10(log10(from)+I*((log10(thru)-log10(from))/numElem))
for I=0..numElem-1

This has the effect that the last element in the resultant array has a value which is less than thru by:

exp10(log10(thru)-log10(from)/numElem).

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Generate
> xlogRamp

See Also

Alloc Real64, logRamp (numElem, from,thru), and xramp (numElem, from,thru).


a XOR b

An object that performs a logical exclusive OR operation on two operands.

Use

Use a XOR b to determine whether one and only one of the value(s) of two containers is logically true (non-zero). The two containers may be of any type and of any shape. If one of the containers is an array, the other must be either a scalar or an array of the same size and shape. The result is an Int32 of the same shape as the operands, with value(s) 0 or 1. If either operand is non-zero, but not both, the value of the XOR operation is 1; otherwise the value is 0.

If both operands are of type Boolean, the result is a Boolean of the same shape as the operands.

If both operands are of type Coord, they must have their independent variable(s) match exactly or an error is returned. Only the dependent (last) variable is considered for the XOR operation.

For Complex, PComplex, and Spectrum containers, the value of the operand is true if either part is non-zero. Text is true if non-null. Enums are converted to Text for the operation.

Example

Two Boolean scalars: True XOR False returns True.

A scalar and an array: 3 XOR [3, 3, 3] returns [0, 0, 0].

A scalar and an array: 3 XOR [-3, 0, 3] returns [0, 1, 0].

Two arrays: [1, 2, 3] XOR [0, 1, (-1)] returns [1, 0, 0].

Two PComplex scalars: (1,@90) XOR (1,@85) returns 0.

Two Complex scalars: (0,0) XOR (0,1) returns 1.

Two Complex scalars: (0,1) XOR (1,0) returns 0.

Two Complex scalars: (0,0) XOR (0,0) returns 0.

Two Coord scalars: coord(1,3) XOR coord(1,5) returns 0.

Two Coord scalars: coord(1,3) XOR coord(2,3) returns an error.

A Text scalar and a scalar number: "too" XOR 0 returns 1.

A Text scalar and a scalar number: "" XOR 0 returns 1 because the real 0 is promoted to "0", which is a non-null string.

Notes

If either of the containers is mapped (that is, of type Waveform, Spectrum, Coord, or a mapped array of any other type), the other container must be unmapped or have identical mappings. The return value will have the same mappings as the operands; otherwise an error is returned.

Note that the If/Then/Else device requires the expression(s) inside it to evaluate to either a scalar or an array, which is either all zeros or all ones.

Location

Device [image] Function & Object Browser

>  Operators
> Logical
> XOR

See Also

a AND b, NOT a, a OR b, Comparison, Conditional and If/Then/Else.


xramp (numElem, from,thru)

An object that generates a linearly ramped array in the same manner used to generate x values for coordinate conversions of mapped 1D Arrays (for example, Waveform).

Use

Use xramp(numElem,from,thru) to generate a Real64 one-dimensional array of length numElem, with the values linearly ramped from from to thru (not inclusive of thru). numElem must be a scalar container that is, or can be converted to, Int32 and with a value greater than zero. from and thru must be scalar containers that are, or can be converted to, Real64.

If from is less than thru, the ramping is positive; otherwise it automatically ramps negatively.

Example

xramp(3, 0.5, 0) returns a one-dimensional array with values
[0.5, 0.3333, 0.1667].

xramp(5, 2, 10) returns a one-dimensional array with values
[2, 3.6, 5.2, 6.8, 8.4].

Notes

The return value has no mappings.

The algorithm for generating values is:

Y[I] = from + I*(thru-from/numElem)
for I=0..numElem-1

This has the effect that the last element in the resultant array has a value which is less than thru by the size of the sampling interval: (thru-from)/numElem.

If you want a ramp that is inclusive of the thru value, use the ramp(numElem,from,thru) function instead.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Generate
> xramp

See Also

Alloc Real64, ramp (numElem, from,thru), and xlogRamp (numElem, from,thru).


y0(x)

An object used to calculate the Bessel function of x of the second kind of order zero.

Use

Use y0(x) to find the Bessel function of x of the second kind of order zero. x may be of any size and shape.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

For Coord input types, the operation is done on the dependent variable.

Example

y0(2) returns 0.510375672649745.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

The value of x must be positive.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> y0

See Also

Ai(x), Bi(x), j0(x), j1(x), jn(x,n), y1(x), and yn(x,n).


y1(x)

An object used to calculate the Bessel function of x of the second kind of order one.

Use

Use y1(x) to find the Bessel function of x of the second kind of order one. x may be of any size and shape.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

For Coord input types, the operation is done on the dependent variable.

Example

y1(9) returns the value 0.104314575196715.

Notes

Mappings on the operand are ignored and the output container has the same mappings as the input.

The value of x must be positive.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> y1

See Also

Ai(x), Bi(x), j0(x), j1(x), jn(x,n), y0(x), and yn(x,n).


year(aDate)

An object that returns the year of the time x.

Use

Use year(aDate) to transform the given time x into a container of the same shape with the value of the year of the time x. x may be any shape, and the same shape is returned.

Allowed Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

Example

year(dmyToDate(25,12,1991)) returns 1991.

Notes

Mappings are retained in the return value.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Time & Date
> year

See Also

dmyToDate (d,m,y), hmsToHour (h,m,s), hmsToSec (h,m,s), mday(aDate), now(), month(aDate), Time & Date, and wday(aDate).


yn(x,n)

An object used to calculate the Bessel function of x of the second kind of order n.

Use

Use yn(x,n) to find the Bessel function of x of the second kind of order n. x may be of any size and shape.

Allowed x Input Type Return Type

UInt8 | Real64
UInt16 | Real64
Int16 | Real64
Int32 | Real64
Int64 | Real64
Real32 | Real64
Real64 | Real64
Coord | Coord
Waveform | Waveform

For Coord input types, the operation is done on the dependent variable.

The n parameter must be of Int32 type or be able to be converted to Int32. The n parameter also must be a Scalar in shape or the same shape as x.

Example

yn(10,4) returns -0.144949511868093.

Notes

If both of the inputs are mapped, then the mappings must be the same. The return value has the same mappings as the input if either input is mapped. If neither of the inputs is mapped, then the output is unmapped.

The value of x must be positive.

Location

Device [image] Function & Object Browser

>  Built-in Functions
> Bessel
> yn

See Also

Ai(x), Bi(x), j0(x), j1(x), jn(x,n), y0(x), and y1(x).


I/O Transactions Summary

Table 1 summarizes I/O transaction types for VEE, and Table 2 summarizes the I/O Transactions Objects for VEE.

Table 1 Summary of I/O Transaction Types

Action | Description
WRITE | Writes data to the destination specified in the object.
READ | Reads data from the source specified in the object.
EXECUTE | Executes low-level commands to control the file, instrument, or interface associated with the object. EXECUTE is used to adjust file pointers, to close pipes and files and to provide low-level control of instruments and hardware interfaces.
WAIT | Waits for the specified number of seconds before executing the next transaction. For Direct I/O objects, WAIT can also wait for a specific serial poll response, or for specific values in accessible VXI instrument registers.
SEND | Sends IEEE 488-defined bus messages (bus commands and data) to a GPIB interface.
READ(REQUEST) | Reads DDE data from another application.
WRITE(POKE) | Writes DDE data to another application.

Table 2 Summary of I/O Transaction Objects

Objects | Supported Transactions
 | EXECUTE | WAIT | READ | WRITE | SEND
To File | X | X |  | X |
From File | X | X | X |  |
To Printer |  | X |  | X |
To String |  | X |  | X |
From String |  | X | X |  |
To/From Socket | X | X | X | X |
Direct I/O | X | X | X | X |
MultiInstrument Direct I/O | X | X | X | X |
Interface Operations | X |  |  |  | X
To/From DDE | X | X | X | X |

See Also

EXECUTE Transactions, READ Transactions, SEND Transactions, WRITE Transactions, WAIT Transactions


WRITE Transactions

This section describes the WRITE transaction in the following table. Topics that apply to all WRITE encodings are summarized at the beginning of this section.

Path-Specific Behaviors

Some WRITE transactions behave differently, depending on the I/O path of the destination. To distinguish these behaviors, this section uses these terms:

• MS-DOS path is any destination other than an instrument, such as an MS-DOS file, a string, or the printer.

• Direct I/O path is any instrument accessed using Direct I/O.

Behaviors for all Paths

The behaviors described in the following table apply to all paths except as specifically noted.

Table WRITE Encodings and Formats

Encodings | Formats
TEXT | DEFAULT STRING QUOTED STRING BYTE WORD INT16 INT32 INT64 BOOLEAN OCTAL HEX REAL32 REAL64 COMPLEX PCOMPLEX COORD TIME STAMP
BYTE | Not Applicable
CASE | Not Applicable
BINARY | STRING BYTE WORD INT16 INT32 INT64 BOOLEAN REAL32 REAL64 COMPLEX PCOMPLEX COORD
BINBLOCK | BYTE WORD INT16 COMPLEX INT32 INT64 BOOLEAN PCOMPLEX REAL32 REAL64 COORD
CONTAINER | Not Applicable
STATE a | Not Applicable
REGISTER b | BYTE WORD16 WORD32 REAL32
MEMORY b | BYTE WORD16 WORD32 REAL32 WORD32*2 REAL64
IOCONTROL c | Not Applicable

a. Direct I/O to GPIB only.

b. Direct I/O to VXI only.

c. Direct I/O to GPIO only.

See Also

TEXT Encoding, BYTE Encoding, CASE Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, STATE Encoding, REGISTER Encoding, MEMORY Encoding, IOCONTROL Encoding


TEXT Encoding

WRITE TEXT transactions are of this form:

WRITE TEXT ExpressionList [Format]

ExpressionList is a single expression or a comma-separated list of expressions.

Format is an optional setting that specifies one of the formats listed in the following table.

Table Formats for WRITE TEXT Transactions

Format | Description
DEFAULT | VEE automatically determines an appropriate text representation based on the data type of the item being written.
STRING | Writes Text data without any conversion. Writes numeric data types as Text with maximum numeric precision.
QUOTED STRING | Writes data in the same format as STRING, except the data is surrounded by double quotes (ASCII 34 decimal).
BYTE | Writes data as an 8-bit two's complement unsigned integer in decimal form
WORD | Writes data as a 16-bit two's complement unsigned integer in decimal form
INT16 | Writes data as a 16-bit two's complement integer in decimal form.
INT32 | Writes data as a 32-bit two's complement integer in decimal form.
INT64 | Writes data as a 64-bit two's complement integer in decimal form
BOOLEAN | Writes data as a Boolean constant (True or False)
OCTAL | Writes data as a 32-bit two's complement integer in octal form.
HEX | Writes data as a 32-bit two's complement integer in hexadecimal form.
REAL32 | Writes data as a 32-bit floating point number in a variety of notations including fixed decimal and scientific notation.
REAL64 | Writes data as a 64-bit floating point number in a variety of notations including fixed decimal and scientific notation.
COMPLEX | Writes a comma-separated pair of 64-bit floating point numbers that represent a complex number. The first number represents the real part and the second number represents the imaginary part.
PCOMPLEX | Writes a comma-separated pair of 64-bit floating point numbers that represent a complex number. The first number represents the magnitude and the second number represents the phase angle in the phase units specified in the transaction.
COORD | Writes a comma-separated series of 64-bit floating point numbers that represent a rectangular coordinate.
TIME STAMP | Converts a real number (for example, the output of the now() function) to a meaningful form and writes it in a variety of combinations of year, month, day and time.

See Also

DEFAULT Format, STRING Format, QUOTED STRING Format, INTEGER Formats, OCTAL Format, HEX Format, REAL32 and REAL64 Format, COMPLEX, PCOMPLEX, and COORD Formats, TIME STAMP Format

BYTE Encoding, CASE Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, STATE Encoding, REGISTER Encoding, MEMORY Encoding, IOCONTROL Encoding


DEFAULT Format

WRITE TEXT (default) transactions are of this form:

WRITE TEXT ExpressionList

ExpressionList is a single expression or a comma-separated list of expressions.

The transaction converts each item in ExpressionList to a meaningful string and writes it. Consider the simple case of writing the scalar variable X as shown below:

  • If X contains text, such as:

bird cat dog

no conversion is performed and the transaction writes exactly 12 characters.

  • If X contains a scalar Integer, such as:

8923 the value of X (decimal notation)

the numeric value is converted to text and VEE writes exactly four characters.

  • If X contains a scalar real value, such as:

1.2345678901234567 the value of X (17-digit scalar real value)

each significant digit up to 16 significant digits is written. The least significant digit is approximate because of the conversion between VEE's internal binary form and decimal notation. If you use this scalar real value using the transaction:

WRITE TEXT a EOL

then VEE writes this:

1.234567890123457 16-digit value

If the absolute value of the number is sufficiently large or small, exponential notation is used. The Reals that form the sub-elements of Coord, Complex, and PComplex behave the same way.

If EOL ON is specified for any WRITE TEXT DEFAULT transaction, the character specified in the EOL Sequence field for that object is written following the last character in ExpressionList.


STRING Format

WRITE TEXT STRING transactions are of this form:

WRITE TEXT ExpressionList STR

ExpressionList is a single expression or a comma-separated list of expressions.

WRITE TEXT STRING transactions behave basically the same as WRITE TEXT (default) transactions (one exception will be discussed). The significant difference is that STRING allows you to specify additional details about output formatting including field width, justification and number of characters.

Field Width and Justification

If a transaction specifies DEFAULT FIELD WIDTH, only those characters resulting from the conversion of items within ExpressionList to Text are written.

If a transaction specifies FIELD WIDTH: F, the converted Text is written right- or left-justified within a space F characters wide.

The transactions below specify that all characters are to be written within a field of twenty characters with left justification.

WRITE TEXT X STR FW:20 LJ EOL
WRITE TEXT Y STR FW:20 LJ EOL

If X and Y have these values:

bird cat dog the Text value of X

12345678901234567 the Real value of Y

then VEE writes:

bird cat dog

12345678901234567

^ ^

The caret characters (^) are not actually written by VEE, but are shown to help you visualize the field width. The characters to the right of dog and to the right of the second 7 are spaces (ASCII 32 decimal).

If justification is changed to RIGHT JUSTIFY, the transactions appear as follows.

WRITE TEXT X STR FW:20 RJ EOL
WRITE TEXT Y STR FW:20 RJ EOL

If X and Y have these values:

bird cat dog the Text value of X

12345678901234567 the Real value of Y

VEE writes:

bird cat dog

12345678901234567

^ ^

The caret characters (^) are not actually written by VEE, but are shown to help you visualize the field width. The characters to the left of bird and to the left of the first 1 are spaces (ASCII 32 decimal).

If the length of a string exceeds the specified field width, the entire string is written. The field width specification never truncates as only MAX NUM CHARS can truncate characters.

The transaction below specifies that all characters are to be written in a field width of four characters with left justification.

WRITE TEXT X STR FW:4 LJ

If X has this value:

bird cat dog the Text value of X, 12 characters

VEE writes:

bird cat dog all 12 characters

Even though the specified field width is four characters, the transaction writes all twelve characters of the string.

Number of Characters

If you specify ALL CHARS, all the characters generated by the conversion of each item in ExpressionList are written. If you specify MAX NUM CHARS: M, only the first M characters of each item in ExpressionList are written.

The transactions below specify that a maximum of seven characters are written in each field, the field width is twenty characters and field entries are left-justified.

WRITE TEXT X STR:7 FW:20 LJ EOL
WRITE TEXT Y STR:7 FW:20 LJ EOL

If X and Y have these values:

bird cat dog the Text value of X

12345678901234567 the Real value of Y

VEE writes:

bird ca

1234567

^ ^

The numeric value of Y is first converted to Text and characters are truncated. Numeric values are not rounded by MAX NUM CHARS.

The caret characters (^) are not actually written by VEE, but are shown to help you visualize the field width. The characters to the right of bird and to the right of the first 1 are spaces (ASCII 32 decimal).

Writing Arrays With Direct I/O

WRITE TEXT STR transactions that write arrays to direct I/O paths ignore the Array Separator setting for the Direct I/O object. These transactions always use linefeed (ASCII decimal 10) to separate each element of an array (which is a string) as it is written. This behavior is consistent with the needs of most instruments.

note

This special behavior for arrays does not apply to any other types of transactions.


QUOTED STRING Format

WRITE TEXT QUOTED STRING transactions are of this form:

WRITE TEXT ExpressionList QSTR

ExpressionList is a single expression or a comma-separated list of expressions.

In general, the behaviors discussed for the STRING format apply to QUOTED STRING format. There are two differences between STRING and QUOTED STRING:

• For QUOTED STRING, a double quote (ASCII 34 decimal) is added to the beginning and the end of the string. The double quotes are applied before any padding spaces are added to justify the string within the specified field width.

• Control characters (ASCII 0-31 decimal), escape characters and the characters ' (ASCII 39 decimal) and " (ASCII 34 decimal) embedded inside a double-quoted string receive special treatment.

Field Width and Justification

If you specify DEFAULT FIELD WIDTH, only those characters resulting from the conversion of items within ExpressionList to Text and the surrounding double quotes are written.

If you specify FIELD WIDTH: F, the converted Text and the surrounding quotes are written right or left justified within a space F characters wide.

The transactions below specify that all characters are to be written as quoted strings in a field 20 characters wide with left justification.

WRITE TEXT X QSTR FW:20 LJ EOL
WRITE TEXT Y QSTR FW:20 LJ EOL

If X and Y have these values:

bird cat dog the Text value of X

12345678901234567 the Real value of Y

VEE writes:

"bird cat dog"

"12345678901234567"

^ ^

The caret characters (^) are not actually written by VEE, but are shown to help you visualize the field width. The characters to the right of dog" and to the right of 7" are spaces (ASCII 32 decimal).

If justification is changed to RIGHT JUSTIFY, the transactions appear as follows.

WRITE TEXT X QSTR FW:20 RJ EOL
WRITE TEXT Y QSTR FW:20 RJ EOL

If X and Y have these values:

bird cat dog the Text value of X

12345678901234567 the Real value of Y

VEE writes:

"bird cat dog"

"12345678901234567"

^ ^

The caret characters (^) are not actually written by VEE, but are shown to help you visualize the field width. The characters to the left of "bird and to the left of "1 are spaces (ASCII 32 decimal).

If the length of a string exceeds the specified field width, the entire string is output. The field width specification never truncates strings that are written as only MAX NUM CHARS can truncate characters.

The transaction below specifies that all characters are to be written within a field of four characters with left justification.

WRITE TEXT X QSTR FW:4 LJ

If X has this value:

bird cat dog the Text value of X, 12 characters

VEE writes:

"bird cat dog" all 12 characters

Number of Characters

If you specify ALL CHARS, all the characters generated by the conversion of each item in ExpressionList as well as the surrounding double quotes are written. If you specify MAX NUM CHARS: M, only the first M characters of each item in ExpressionList plus the surrounding double quotes are written. In other words, a total of M+2 characters are written for each item in ExpressionList.

The transaction below specifies MAX NUM CHARS:7 (field width 20, left-justified).

WRITE TEXT X QSTR:7 FW:20 LJ EOL
WRITE TEXT Y QSTR:7 FW:20 LJ EOL

If X and Y have these values:

bird cat dog the Text value of X

12345678901234567 the Real value of Y

VEE writes:

"bird ca"

"1234567"

^ ^

The caret characters (^) are not actually written by VEE, but are shown to help you visualize the field width. The characters to the right of ca" and to the right of 7" are spaces (ASCII 32 decimal).

Embedded Control and Escape Characters

In this discussion, the terms control character and escape character have specific meaning. A control character is a single byte of data corresponding to one of the ASCII characters 0-31 decimal. For example, linefeed is ASCII 10 decimal and the symbol <LF> denotes linefeed character in this discussion. The string \n is a human-readable escape character representing linefeed that is recognized by VEE. VEE uses escape characters to represent control characters within quoted strings.

See the following figure for Escape Characters.

Escape Character | ASCII Code (decimal) | Meaning
\n | 10 | Newline
\t | 9 | Horizontal Tab
\v | 11 | Vertical Tab
\b | 8 | Backspace
\r | 13 | Carriage Return
\f | 12 | Form Feed
\" | 34 | Double Quote
\' | 39 | Single Quote
\\ | 92 | Backslash
\ddd |  | The ASCII character corresponding to the three-digit octal value ddd.

Consider the effects of various embedded escape characters on the transaction below.

WRITE TEXT X QSTR EOL

  • If X has this value:

bird\ncat dog

VEE writes this to direct I/O paths:

"bird<LF>cat dog"

where <LF> means the single character, linefeed (ASCII 10 decimal).

  • If X has this value:

bird \"cat\" dog

VEE writes this to Direct I/O paths for serial interfaces:

"bird \"cat\" dog"

For the same transaction and data, VEE writes this to direct I/O paths for GPIB interfaces:

"bird ""cat"" dog"

This unique behavior for GPIB interfaces is provided to support the requirements of IEEE 488.2.


INTEGER Formats

WRITE TEXT INTEGER transactions are of this form:

WRITE TEXT ExpressionList BYTE

WRITE TEXT ExpressionList WORD

WRITE TEXT ExpressionList INT16

WRITE TEXT ExpressionList INT32

WRITE TEXT ExpressionList INT64

ExpressionList is a single expression or a comma-separated list of expressions.

The type of integer generated by this transaction is listed in the following table. The only characters written to represent these numbers are +-0123456789.

Integer format | Type of integer generated by transaction | Range of integer
BYTE | 8-bit two's complement unsigned integer | 0 to + 255
WORD | 16-bit two's complement unsigned integer | 0 to + 65 535
INT16 | 16-bit two's complement integer | -32 768 to + 32 767
INT32 | 32-bit two's complement integer | -2 147 483 648 to + 2 147 483 647
INT64 | 64-bit two's complement integer | 9 223 372 036 854 775 808 to + 9 223 372 036 854 775 807

VEE attempts to convert each item in ExpressionList to the Int64, Int32, Int16, UInt16, or UInt8 data type before converting it to Text for final formatting. VEE follows the usual conversion rules. See the Data Type Conversion topics under Help => Contents and Index => Tell Me About... for more details.

If a Real32 or Real64 is written using UInt8, UInt16, INT16, INT32,or INT64 format:

• Real values outside the valid range of the corresponding integer type generate an error.

• Real values within the valid range of the corresponding integer type are converted by truncating the fractional portion of the Real.

Number of Digits

If you specify DEFAULT NUM DIGITS, the transaction writes only the digits required to express the value of the integer and leading zeros are not used.

If you specify MIN NUM DIGITS: M, the transaction pads the output with leading zeros as required to give a total of exactly M digits.

Consider the two Int16 or Int32 transactions below, which differ only in their specification for the number of output digits.

WRITE TEXT X INT16 EOL default number of digits
WRITE TEXT X INT16:6 EOL six digits

or

WRITE TEXT X INT32 EOL default number of digits

WRITE TEXT X INT32:6 EOL six digits

If X has this value:

4567

VEE writes:

4567

004567

MIN NUM DIGITS never causes truncation of the output string. The transaction below specifies the minimum number of digits to be 1.

WRITE TEXT X INT16:1 EOL

or

WRITE TEXT X INT32:1 EOL

If X has a value of:

12345678

VEE writes:

12345678 all eight digits

Sign Prefixes

You may optionally specify one of the sign prefixes listed in the following table as part of a WRITE TEXT INT transaction.

Prefix | Description
/- | Positive numbers are written with no prefix, neither a + nor a space. All negative numbers are written with a - prefix.
+/- | All positive numbers are written with a + prefix. All negative numbers are written with a - prefix.
" "/- | All positive numbers are written with a space (ASCII 32 decimal) prefix. All negative numbers are written with a - prefix.

Any prefixed signs do not count towards MIN NUM DIGITS. The transaction shown below specifies explicit leading signs for positive and negative numbers.

WRITE TEXT X INT16:6 SIGN:"+/-" EOL
WRITE TEXT Y INT32:6 SIGN:"+/-" EOL

If X and Y have values of:

123 the Integer value of X

-123 the Integer value of Y

VEE writes:

+000123 six digits plus sign

-000123


OCTAL Format

WRITE TEXT OCTAL transactions are of this form:

   WRITE TEXT ExpressionList OCT

ExpressionList is a single expression or a comma-separated list of expressions.

The type of integer written by this transaction is a 64-bit two's complement integer. The range of these integers is -9223372036854775808 to +9223372036854775807. The only characters written to represent these octal numbers are 01234567. An optional prefix may be specified which may include other characters.

VEE attempts to convert any data written using OCTAL format to the Int64 data type before converting it to Text for final formatting. The usual VEE conversion rules are followed.

If a Real is written using OCTAL format:

• Real values outside the valid range of Int64 generate an error.

• Real values within the valid range of Int64 are converted by truncating the fractional portion of the Real.

Number of Digits

The behavior of DEFAULT NUM DIGITS and MIN NUM DIGITS is the same as described in Number of Digits for WRITE TEXT INTEGER transactions.

Octal Prefixes

You may specify one of the prefixes listed in the following table as part of a WRITE TEXT OCTAL transaction.

Prefix | Description
NO PREFIX | VEE writes each octal number without any prefix. Only the digits 01234567 appear in the output.
DEFAULT PREFIX | For direct I/O paths, VEE prefixes each octal number with #Q. This supports the octal Non-Decimal Numeric data format defined by IEEE 488.2.
PREFIX:string | VEE prefixes each octal number with the characters specified in string.

The transaction below specifies the default prefix and six digits:

WRITE TEXT X OCT:6 PREFIX EOL

  • If X has this value:

15 the value 15 decimal

VEE writes this to direct I/O paths:

#Q000017 exactly six digits plus prefix

The transaction below specifies a custom prefix and ten digits:

WRITE TEXT X OCT:10 PREFIX:"oct>" EOL

  • If X has this value:

15 the Integer value 15 decimal

VEE writes this to direct I/O paths:

oct>000017

The prefix written by DEFAULT PREFIX depends on the destination, but the prefix written by PREFIX: string is independent of the destination.


HEX Format

WRITE TEXT HEX transactions are of this form:

   WRITE TEXT ExpressionList HEX

The type of integer written by this transaction is a 64-bit two's complement integer. The range of these integers is --9223372036854775808 to +9223372036854775807. The only characters written to represent these hexadecimal numbers are 0123456789abcdef. An optional prefix may be specified that may include other characters.

The behavior of WRITE TEXT HEX is nearly identical to that of WRITE TEXT OCTAL. The only difference is the set of prefixes available and the behavior of DEFAULT PREFIX.

Hexadecimal Prefixes

You may specify one of the prefixes listed below as part of a WRITE TEXT HEX transaction.

Prefix | Description
NO PREFIX | VEE writes each hexadecimal number without any prefix. Only the digits 0123456789abcdef appear in the output.
DEFAULT PREFIX | For direct I/O paths, VEE prefixes each hexadecimal number with #H. This supports the hexadecimal Non-Decimal Numeric data format defined by IEEE 488.2.
PREFIX:string | VEE prefixes each hexadecimal number with the characters specified in string.

The transaction below specifies the default prefix and six digits:

WRITE TEXT X HEX:6 PREFIX EOL

If X has this value:

15 the Integer value 15 decimal

VEE writes this to direct I/O paths:

#H00000f exactly six digits plus prefix

The transaction below specifies a custom prefix and three digits:

WRITE TEXT X HEX:3 PREFIX:"hex>" EOL

If X has this value:

15 the Integer value 15 decimal

VEE writes this to direct I/O paths:

hex>00f exactly three digits plus prefix

The prefix written by DEFAULT PREFIX depends on the destination, but the prefix written by PREFIX: string is independent of the destination.


REAL32 and REAL64 Format

WRITE TEXT REAL32 transactions are of the form shown below:

WRITE TEXT ExpressionList REAL32

The type of Real number generated by this transaction is a 32-bit IEEE 754 floating-point number. The range of these numbers is:

-3.40282347E38 to 3.40282347E38

WRITE TEXT REAL64 transactions are of the form shown below:

WRITE TEXT ExpressionList REAL64

The type of Real number generated by this transaction is a 64-bit IEEE 754 floating-point number. The range of these numbers is:

-1.797 693 134 862 315E+308 to 1.797 693 134 862 315E+308

The only characters written to represent these numbers are
+-.0123456789E.

Notations and Digits

You may optionally specify one of the notations below as part of a WRITE TEXT REAL transaction.

Notation | Description
STANDARD | VEE automatically determines whether each Real value should be written in fixed-point notation (decimal points as required, no exponents) or in exponential notation. Non-significant zeros are never written.
FIXED | VEE writes each Real value as a fixed-point number. Numbers with fractional digits are automatically rounded to fit the number of fractional digits specified by NUM FRACT DIGITS. Trailing zero digits are added as required to give the specified number of fractional digits.
SCIENTIFIC | VEE writes each Real value using exponential notation. Each exponent includes an explicit sign (+ or -) and the upper-case E is always used. Numbers with fractional digits are automatically rounded to fit the number of fractional digits specified by NUM FRACT DIGITS. Trailing zero digits are added as required to give the specified number of fractional digits.

The transactions below specify STANDARD notation and four significant digits.

WRITE TEXT X REAL32 STD:4 EOL
WRITE TEXT Y REAL64 STD:4 EOL
WRITE TEXT Z REAL32 STD:4 EOL

If X, Y and Z have these values:

1.23456E2 the Real32 value of X

1.23456E09 the Real64 value of Y

1.23 the Real32 value of Z

VEE writes:

123.5 mantissa rounded as required

1.235E+09 large numbers in exponential notation

1.23 never any trailing zeros

The transactions below specify FIXED notation and four fractional digits.

WRITE TEXT X REAL64 FIX:4 EOL
WRITE TEXT Y REAL32 FIX:4 EOL
WRITE TEXT Z REAL64 FIX:4 EOL

If X, Y and Z have these values:

1.2345678E2 the Real64 value of X

1.2345678E-09 the Real32 value of Y

1.23 the Real64 value of Z

VEE writes:

123.4568 mantissa rounded as required

0.0000 small numbers round to zero

1.2300 trailing zeros added as required

The transactions below specify SCIENTIFIC notation and four fractional digits.

WRITE TEXT X REAL32 SCI:4 EOL
WRITE TEXT Y REAL64 SCI:4 EOL
WRITE TEXT Z REAL32 SCI:4 EOL

If X, Y and Z have these values:

1.2345678E2 the Real32 value of X

-1.2345678E-09 the Real64 value of Y

0 the Real32 value of Z

VEE writes:

1.2346E+02 exponent is E plus two signed digits

-1.2346E-09 last digit rounded as required

0.0000E+00 trailing zeros padded as required


COMPLEX, PCOMPLEX, and COORD Formats

COMPLEX, PCOMPLEX, and COORD correspond to the VEE multi-field data types with the same names. The behavior of all three formats is very similar. The behaviors described in this section apply to all three formats except as noted.

Just as the VEE data types Complex, PComplex, and Coord are composed of multiple Real numbers, the COMPLEX, PCOMPLEX, and COORD formats are essentially compound forms of the REAL64 format. Each constituent Real value of the multi-field data types is written with the same output rules that apply to an individual REAL64 formatted value.

The final output of transactions involving multi-field formats is affected by the Multi-Field Format setting for the object in question. Multi-Field Format is accessed via I/O => Instrument Manager for Direct I/O objects and via Config in the object menu for all other objects. The two possible settings for Multi-Field Format are:

• Data Only. This writes multi-field data formats as a list of comma-separated numbers without parentheses.

• (...) Syntax. This writes multi-field data formats as a list of comma-separated numbers grouped by parentheses.

Subsequent examples will illustrate these behaviors.

COMPLEX Format

WRITE TEXT COMPLEX transactions are of this form:

WRITE TEXT ExpressionList CPX

The transaction below specifies a fixed-decimal notation, explicit leading signs, a field width of 10 characters and right justification.

WRITE TEXT X CPX FIX:3 SIGN:"+/-" FW:10 RJ EOL

  • If the Multi-Field Format is set to (...) Syntax and X has this value:

( -1.23456 , 9.8 ) the Complex value of X

VEE writes:

( -1.235 , +9.800)

^ ^ ^ ^

  • If the Multi-Field Format is set to Data Only and X has the same value, VEE writes:

-1.235, +9.800

^ ^ ^ ^

The caret characters (^) are not actually written by VEE, but are shown to help you visualize the field width. The characters to the left of + are spaces (ASCII 32 decimal).

With (...) Syntax, a space-comma-space sequence separates the ten-character wide fields that contain the real and imaginary parts of the Complex number. With either Multi-Field Format there is a separate ten-character field for both the real and the imaginary part. Neither parentheses nor the separating comma and spaces are included in the field.

PCOMPLEX Format

WRITE TEXT PCOMPLEX transactions are of this form:

WRITE TEXT ExpressionList PCX

PCOMPLEX format allows you to specify the phase units for the polar complex number it writes. Phase units are independent of the units set by Trig Mode in Properties. See the following figure.

Unit | Description
DEG | Degrees
RAD | Radians
GRAD | Gradians

The first transaction below specifies phase measurement in degrees and the second transaction specifies phase measurement in radians.

WRITE TEXT X PCX:DEG STD EOL
WRITE TEXT X PCX:RAD STD EOL

If the Multi-Field Format is set to Data Only and X has this value:

(-1.23456, @90) the PComplex value of X, phase in degrees

VEE writes:

1.23456,-90

1.23456,-1.570796326794897

The transaction below specifies phase measurement in radians, fixed-decimal notation, three fractional digits, explicit leading signs, a field width of ten characters and right justification.

WRITE TEXT X PCX:RAD FIX:3 SIGN:"+/-" FW:10 RJ EOL

  • If the Multi-Field Format is set to (...) Syntax and X has this value:

(-1.23456 , @9.8) the PComplex value of X, angle in radians

VEE writes:

( +1.235 , @ +0.375)

^ ^ ^ ^

VEE normalizes all PComplex numbers to yield a positive magnitude and a phase between +p and -p.

  • If the Multi-Field Format is set to Data Only and X has the same value, VEE writes:

+1.235, +0.375

^ ^ ^ ^

The caret characters (^) are not actually written by VEE, but are shown to help you visualize the field width. The characters to the left of - and to the left of + are spaces (ASCII 32 decimal).

COORD Format

WRITE TEXT COORD transactions are of this form:

WRITE TEXT ExpressionList COORD

COORD format has all the same behaviors of COMPLEX format. The only difference is that COORD may contain an arbitrary number of fields while COMPLEX has exactly two fields.


TIME STAMP Format

WRITE TEXT TIME STAMP transactions are of this form:

WRITE TEXT ExpressionList [DATE:DateSpec] [TIME:TimeSpec]

ExpressionList is a single expression or a comma-separated list of expressions.

DateSpec is one of the following pre-defined date and time combinations:

• Date

• Time

• Date&Time

• Time&Date

• Delta Time

If you specify a transaction that includes Date, you may also specify a DateSpec of Weekday DD/Month/YYYY or
DD/Month/YYYY.

If you specify a transaction that includes Time, you may also specify a TimeSpec. TimeSpec is a combination of the following pre-defined time formats:

• HH:MM (hours and minutes)

• HH:MM:SS (hours, minutes and seconds)

• 12 HOUR

• 24 HOUR

Each item in ExpressionList is converted to a Real and interpreted as a date and time. This Real number represents the number of seconds that have elapsed since midnight, January 1, AD 1 UTC. The most common source for this Real number is the output of a Time Stamp object. You use the TIME STAMP format to convert this Real number to a meaningful string that contains a human-readable date and/or time.

TIME STAMP supports a variety of notations for writing dates and times. If a Real variable contains this value:

62806574669.31164

TIME STAMP can write it using any of the Time and Date notations below.

Notation

Result

Date with Weekday
DD/Month/YYYY

Thu 04/Apr/1999

Time with HH:MM:SS and 24 HOUR

15:44:29

Date&Time with Weekday
DD/Month/YYYY, HH:MM:SS,
and 24 HOUR

Thu 04/Apr/1999 15:44:29

Time&Date with HH:MM:SS, 24 HOUR

and Weekday DD/Month/YYYY

15:44:29 Thu 04/Apr/1999

Delta Time with HH:MM:SS

17446270:44:29

Date with Weekday
DD/Month/YYYY

Thu 04/Apr/1999

Date with DD/Month/YYYY

04/Apr/1999

Time with HH:MM:SS and 24 HOUR

15:44:29

TIME with HH:MM and 24 HOUR

15:44

TIME with HH:MM:SS and 24 Hour

15:44:29

TIME with HH:MM:SS and 12 Hour

3:44:29 PM


BYTE Encoding

BYTE transactions are of this form:

WRITE BYTE ExpressionList

ExpressionList is a single expression or a comma-separated list of expressions.

VEE 5 or earlier Execution Mode converts each item in ExpressionList to an Int16 (16-bit two's complement integer) and writes the least-significant 8-bits. VEE 6 Execution Mode converts each item in ExpressionList to a UInt8 (8-bit two’s complement integer) and writes it. This is a transaction for writing single characters to a instrument. Each expression in ExpressionList must be a scalar.

In VEE 6 or later Execution Mode, a value greater than 256 causes an error. For example, in VEE 5 and lower Execution Modes, the transactions below produce the following character data output:

   ABCAA

WRITE BYTE 65,66,67
WRITE BYTE 65+1024,65+2048

In VEE 6 or later Execution Mode, the second transaction above will cause an error.

See Also

TEXT Encoding, CASE Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, STATE Encoding, REGISTER Encoding, MEMORY Encoding, IOCONTROL Encoding


CASE Encoding

WRITE CASE transactions are of this form:

WRITE CASE ExpressionList1 OF ExpressionList2

ExpressionList is a single expression or a comma-separated list of expressions.

VEE converts each item in ExpressionList1 to an integer and uses it as an index into ExpressionList2. The indexed item(s) in ExpressionList2 are written in a string format that is the same as WRITE TEXT (default).

Indexing of items in ExpressionList2 is zero-based.

The transactions below illustrate the behavior of CASE format.

WRITE CASE 2,1 OF "Str0","Str1","Str2"
WRITE CASE X OF 1,1+A,3+A

If the variables have these values:

2 the Real32 value of X

0.1 the Real64 value of A

VEE writes:

Str2Str1

3.1

See Also

TEXT Encoding, BYTE Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, STATE Encoding, REGISTER Encoding, MEMORY Encoding, IOCONTROL Encoding


BINARY Encoding

WRITE BINARY transactions are of this form:

WRITE BINARY ExpressionList DataType

ExpressionList is a single expression or a comma-separated list of expressions.

DataTypes is one of the following pre-defined VEE data types:

• Boolean - 32-bit two's complement integer

• BYTE - 8-bit unsigned byte

• WORD - 16-bit two's complement unsigned integer

• INT16 - 16-bit two's complement integer

• INT32 - 32-bit two's complement integer

• INT64 - 64-bit two's complement integer

• REAL32 - 32-bit IEEE 754 floating-point number

• REAL64 - 64-bit IEEE 754 floating-point number

• STRING - null terminated string

• COMPLEX - equivalent to two REAL64s

• PCOMPLEX -equivalent to two REAL64s

• COORD - equivalent to two or more REAL64s

note

VEE 5 and lower Execution Modes store and manipulate all integer values as the INT32 data type and all real numbers as the Real data type, also known as REAL64. Thus, the INT16 and REAL32 data types are provided for I/O only. VEE 5 and lower Execution Modes perform the following data-type conversions for instrument I/O on an output transaction.

INT32 values are individually converted to INT16 values, which are output to the instrument. However, since the INT16 data type has a range of -32768 to 32767, values outside this range will be truncated to 16 bits.

REAL64 values are individually converted to REAL32 values, which are output to the instrument. However, since the REAL32 data type has a smaller range than REAL64 data type, values outside this range cannot be converted to REAL32 and will result in an error.

In VEE 6 Execution Mode, the data is converted to the appropriate type, and an error is generated if the data is out of range.

BINARY encoded transactions convert each of the values specified in ExpressionList to the VEE data type specified by DataType. Each converted item is then written in the specified binary format. However, since the binary data written is a copy of the representation in computer memory, it is not easily shared by different computer architectures or hardware.

BINARY encoded data has the advantage of being very compact. READ BINARY transactions can read any corresponding WRITE BINARY data.

BINARY encoding writes only the numeric portion of each data type. For example, the parentheses and comma that can be included when writing Complex and Coord data with TEXT encoding are never written with BINARY encoding.

Similarly, when writing arrays, BINARY encoding does not write any Array Separators. WRITE BINARY transactions do allow you to specify EOL ON. There is rarely a need to write EOL with BINARY transactions because numeric data types are of fixed length and strings are null-terminated.

See Also

TEXT Encoding, BYTE Encoding, CASE Encoding, BINBLOCK Encoding, CONTAINER Encoding, STATE Encoding, REGISTER Encoding, MEMORY Encoding, IOCONTROL Encoding


BINBLOCK Encoding

WRITE BINBLOCK transactions are of this form:

WRITE BINBLOCK ExpressionList DataType

ExpressionList is a single expression or a comma-separated list of expressions.

DataType is one of these pre-defined VEE data types:

• Boolean - 32-bit two's complement integer

• BYTE - 8-bit unsigned byte

• WORD - 16-bit unsigned integer

• INT16 - 16-bit two's complement integer

• INT32 - 32-bit two's complement integer

• INT64 - 64-bit two's complement integer

• REAL32 - 32-bit IEEE 754 floating-point number

• REAL64 - 64-bit IEEE 754 floating-point number

• STRING - null terminated string

• COMPLEX - equivalent to two REAL64s

• PCOMPLEX -equivalent to two REAL64s

• COORD - equivalent to two or more REAL64s

BINBLOCK writes each item in ExpressionList as a separate data block. The block header used depends on the type of object performing the WRITE and the object's configuration.

Non-GPIB BINBLOCK

If the object is not Direct I/O to GPIB, a WRITE BINBLOCK always writes an IEEE 488.2 Definite Length Arbitrary Block Response Data block. This data format is primarily used for communicating with GPIB instruments using Direct I/O, although it is supported by other objects.

Each Definite Length Arbitrary Block is of the form:

#<Num_digits><Num_bytes><Data>

where:

  • # is literally the # character as shown.

  • <Num_digits> is an ASCII character that is a single digit (decimal notation) indicating the number of digits in <Num_bytes>.

  • <Num_bytes> is a list of ASCII characters that are digits (decimal notation) indicating the number of bytes that follow in <Data>.

  • <Data> is a sequence of arbitrary 8-bit data bytes.

GPIB BINBLOCK

If the object is Direct I/O to GPIB, the behavior of WRITE BINBLOCK transactions depends upon the Direct I/O Configuration settings for Conformance and Binblock; these settings are accessed via the I/O => Instrument Manager menu selection.

If Conformance is set to IEEE 488.2, WRITE BINBLOCK always writes an IEEE 488.2 Definite Length Arbitrary Block Response Data block.

If Conformance is set to IEEE 488, the type of header used depends on Binblock. Binblock may specify IEEE 728 #A, #T, or #I block headers. If Binblock is None, WRITE BINBLOCK writes an IEEE 488.2 Definite Length Arbitrary Block Response Data block.

IEEE 728 block headers are of the following forms:

#A<Byte_Count><Data>

#T<Byte_Count><Data>

#I<Data><END>

where:

  • # is the character as shown.

  • A,T, I are the characters as shown.

  • <Byte_Count> consists of two bytes which together form a 16-bit unsigned integer that specifies the number of bytes that follow in <Data>. (VEE calculates this automatically.)

  • <Data> is a stream of arbitrary bytes.

  • <END> indicates that EOI is asserted with the last data byte transmitted.

See Also

TEXT Encoding, BYTE Encoding, CASE Encoding, BINARY Encoding, CONTAINER Encoding, STATE Encoding, REGISTER Encoding, MEMORY Encoding, IOCONTROL Encoding


CONTAINER Encoding

WRITE CONTAINER transactions are of this form:

WRITE CONTAINER ExpressionList

ExpressionList is a single expression or a comma-separated list of expressions.

A WRITE CONTAINER transaction writes each item in ExpressionList using a special VEE text representation.

This representation retains all the VEE attributes associated with the data type written, such as shape, size and name. Any WRITE CONTAINER data can be retrieved without any loss of information using READ CONTAINER.

For example, this transaction:

WRITE CONTAINER 1.2345

writes:

(Real

(data 1.2345)

)

See Also

TEXT Encoding, BYTE Encoding, CASE Encoding, BINARY Encoding, BINBLOCK Encoding, STATE Encoding, REGISTER Encoding, MEMORY Encoding, IOCONTROL Encoding


STATE Encoding

WRITE STATE transactions are of the form:

WRITE STATE [DownloadString]

DownloadString is an optional string that allows you to specify a download string if you have not previously specified one in the direct I/O configuration for the corresponding instrument. This explained in greater detail in the sections that follow.

WRITE STATE transactions are used by Direct I/O objects to download a learn string to an instrument. There is exactly one learn string associated with each instance of a Direct I/O object. This learn string is uploaded by clicking Upload in the Direct I/O object menu. The learn string contains the null string before Upload is selected for the first time.

The behavior of WRITE STATE is affected by the Direct I/O Configuration settings for Conformance and Download String. These settings are accessed via the I/O => Instrument Manager menu selection. If Conformance is IEEE 488, the WRITE STATE transaction writes the Download String followed by the learn string. If Conformance is IEEE 488.2, the learn string is downloaded without any prefix as defined by IEEE 488.2. See Controlling Instruments with VEE for information about WRITE STATE transactions.

See Also

TEXT Encoding, BYTE Encoding, CASE Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, REGISTER Encoding, MEMORY Encoding, IOCONTROL Encoding


REGISTER Encoding

WRITE REGISTER is used to write values into a VXI instrument's A16 memory.

WRITE REGISTER transactions are of this form:

WRITE REG: SymbolicName ExpressionList INCR

-or-

WRITE REG: SymbolicName ExpressionList

where:

SymbolicName is a name defined during configuration of a VXI instrument. The name refers to a specific address within a instrument's register space. Specific data types for WRITE REGISTER transactions are:

• BYTE - 8 bit unsigned byte

• WORD16 - 16-bit two's complement integer

• WORD32 - 32-bit two's complement integer

• REAL32 - 32-bit IEEE 754 floating point number

• WORD32*2 - two 32-bit two’s complement integers in adjacent elements of an Int32 array.

• REAL64 - 64-bit

These data types are also specified during configuration of a VXI instrument and do not appear in the transaction.

ExpressionList is a single expression or a comma-separated list of expressions.

INCR specifies that array data is to be written incrementally starting at the register address specified by SymbolicName. The first element of the array is written at the starting address, the second at that address plus an offset equal to the length in bytes of the data type, etc. until all array elements have been written. If INCR is not specified in the transaction, the entire array is written to the single location specified by SymbolicName.

See Also

TEXT Encoding, BYTE Encoding, CASE Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, STATE Encoding, MEMORY Encoding, IOCONTROL Encoding


MEMORY Encoding

WRITE MEMORY is used to write values into a VXI instrument's A24 or A32 memory.

WRITE MEMORY transactions are of this form:

WRITE MEM: SymbolicName ExpressionList INCR

-or-

WRITE MEM: SymbolicName ExpressionList

where:

SymbolicName is a name defined during configuration of a VXI instrument. The name refers to a specific address within a instrument's extended memory. Specific data types for WRITE MEMORY transactions are:

• BYTE - 8 bit unsigned byte

• WORD16 - 16-bit two's complement integer

• WORD32 - 32-bit two's complement integer

• REAL32 - 32-bit IEEE 754 floating point number

• WORD32*2 - two 32-bit two’s complement integers in adjacent elements of an Int32 array.

• REAL64 - 64-bit IEEE 754 floating point number.

These data types are also specified during configuration of a VXI instrument and do not appear in the transaction.

ExpressionList is a single expression or a comma-separated list of expressions.

INCR specifies that array data is to be written incrementally starting at the memory location specified by SymbolicName. The first element of the array is written at that location, the second at that location plus an offset equal to the length in bytes of the data type, etc. until all array elements have been written. If INCR is not specified in the transaction, the entire array is written to the single memory location specified by SymbolicName.

See Also

TEXT Encoding, BYTE Encoding, CASE Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, STATE Encoding, REGISTER Encoding, IOCONTROL Encoding


IOCONTROL Encoding

WRITE IOCONTROL transactions are of this form:

WRITE IOCONTROL CTL ExpressionList

-or-

WRITE IOCONTROL PCTL ExpressionList

ExpressionList is a single expression or a comma-separated list of expressions.

IOCONTROL encoding is used only for Direct I/O to GPIO interfaces.

This transaction sets the control lines of a GPIO interface:

WRITE IOCONTROL CTL a

VEE converts the value of a to an Integer. The least X significant bits of the Integer value are mapped to the control lines of the interface, where X is the number of control lines.

For example, the HP 98622A GPIO interface uses two control lines, CTL0 and CTL1. .

Value Written | CTL1 | CTL0
0 | 0 | 0
1 | 0 | 1
2 | 1 | 0
3 | 1 | 1

In the table above, 1 indicates a control line is asserted and 0 indicates it is cleared. This transaction controls the computer-driven handshake line of a GPIO interface:

WRITE IOCONTROL PCTL a

If the value of a is non-zero, the PCTL line is set. If the value is zero, no action is taken. PCTL is cleared automatically by the interface when the peripheral meets the handshake requirements.

See Also

TEXT Encoding, BYTE Encoding, CASE Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, STATE Encoding, REGISTER Encoding, MEMORY Encoding


READ Transactions

See the following table for Read Encodings and Formats.

Encodings | Formats
TEXT | CHAR TOKEN STRING QUOTED STRING BYTE INT16 INT32 INT64 BOOLEAN OCTAL HEX REAL32 REAL64 COMPLEX PCOMPLEX COORD TIME STAMP
BINARY | STR BYTE INT16 INT32 INT64 BOOLEAN REAL32 REAL64 COMPLEX PCOMPLEX COORD
BINBLOCK | BYTE INT16 INT32 INT64 BOOLEAN REAL32 REAL64 COMPLEX PCOMPLEX COORD
CONTAINER | Not Applicable
IOSTATUS | Not Applicable
REGISTERa | BYTE WORD16 WORD32 REAL32
MEMORYa | BYTE WORD16 WORD32 WORD32*2 REAL32 REAL64

a. Direct I/O to VXI only.

See Also

TEXT Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, IOSTATUS Encoding,

REGISTER Encoding, MEMORY Encoding

General Notes for READ TEXT


TEXT Encoding

READ TEXT transactions can read and discard what is irrelevant and selectively read what is important. This works well most of the time, but occasionally you must analyze very carefully what VEE considers to be irrelevant and what it considers to be important.

This will rarely (if ever) be a problem if you are reading text files written by VEE as long as you read them using the same format used to write them. Problems are most likely to occur when you are trying to import a file from another software application.

The following table describes READ TEXT behavior in a general way only. Be sure to read all the sections that follow to understand all the possible variations.

Format | Description
CHAR | Reads any 8-bit character.
TOKEN | Reads a contiguous list of characters as a unit called a token. Tokens are separated by specified delimiter characters (you specify the delimiters). For example, in normal written English, words are tokens and spaces are delimiters.
STRING | Reads a list of 8-bit characters as a unit. Most control characters are read and discarded. The end of the string is reached when the specified number of characters has been read or when a newline character is encountered.
QSTRING | Reads a list of 8-bit characters that conform to the IEEE 488.2 arbitrary length string defined by a starting and ending double quote character (ASCII 34). Control characters are not discarded. Escaped characters are expanded to a corresponding control character. The end of the string is reached when the double quote character (ASCII 34) has been read.
BYTE | Reads a list of characters and interprets them as a decimal or non-decimal representation of a 8-bit integer. The only characters considered to be part of a decimal INTEGER are 0123456789-+. VEE recognizes the prefix 0x (hex) and all the Non-Decimal Numeric formats specified by IEEE 488.2: #H (hex), #Q (octal), #B (binary).
INTEGER16 | Reads a list of characters and interprets them as a decimal or non-decimal representation of a 16-bit integer. The only characters considered to be part of a decimal INTEGER are 0123456789-+. VEE recognizes the prefix 0x (hex) and all the Non-Decimal Numeric formats specified by IEEE 488.2: #H (hex), #Q (octal), #B (binary).
INTEGER32 | Reads a list of characters and interprets them as a decimal or non-decimal representation of a 32-bit integer. The only characters considered to be part of a decimal INTEGER are 0123456789-+. VEE recognizes the prefix 0x (hex) and all the Non-Decimal Numeric formats specified by IEEE 488.2: #H (hex), #Q (octal), #B (binary).
INTEGER64 | Reads a list of characters and interprets them as a decimal or non-decimal representation of a 64-bit integer. The only characters considered to be part of a decimal INTEGER are 0123456789-+. VEE recognizes the prefix 0x (hex) and all the Non-Decimal Numeric formats specified by IEEE 488.2: #H (hex), #Q (octal), #B (binary).
BOOLEAN | Reads a list of characters and interprets them as a boolean data.
OCTAL | Reads a list of characters and interprets them as the octal representation of an integer. The characters considered to be part of an OCTAL are 01234567. VEE also recognizes the IEEE 488.2 Non-Decimal Numeric prefix #Q for octal numbers.
HEX | Reads a list of characters and interprets them as the hexadecimal representation of an integer. The only characters considered to be part of a HEX are 0123456789abcdefABCDEF. The character combination 0x is the default prefix; it is not part of the number and is read and ignored. VEE also recognizes 0x and the IEEE 488.2 Non-Decimal Numeric prefix #H for hexadecimal numbers.
REAL32 | Reads a list of characters and interprets them as the decimal representation of a Real 32-bit (floating-point) number. All common notations are recognized including leading signs, signed exponents and decimal points. The characters recognized to be part of a REAL32 are 0123456789-+.Ee. VEE also recognizes certain characters as suffix multipliers for Real numbers (see this Table).
REAL64 | Reads a list of characters and interprets them as the decimal representation of a Real 64-bit (floating-point) number. All common notations are recognized including leading signs, signed exponents and decimal points. The characters recognized to be part of a REAL are 0123456789-+.Ee. VEE also recognizes certain characters as suffix multipliers for Real numbers (see this Table).
COMPLEX | Reads the equivalent of two REAL64s and interprets them as a complex number. The first number read is the real part and the second number read is the imaginary part.
PCOMPLEX | Reads the equivalent of two REAL64s and interprets them as a complex number in polar form. Some engineering disciplines refer to this as "phasor notation". The first number read is considered to be the magnitude and the second is the angle. You may specify units of measure for phase in the transaction.
COORD | Reads the equivalent of two or more REAL64s and interprets them as rectangular coordinates.
TIME STAMP | Reads one of the specified VEE time stamp formats which represent the calendar date and/or time of day.

See Also

CHAR Format, TOKEN Format, STRING Format, QUOTED STRING Format, INT16 and INT32 Formats, REAL32 and REAL64 Format, HEX Format, OCTAL Format, COMPLEX, PCOMPLEX and COORD Formats

BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, IOSTATUS Encoding,

REGISTER Encoding, MEMORY Encoding


General Notes for READ TEXT

Read to End

The READ TEXT formats support a choice between reading a specified number of elements or reading until EOF is encountered. In a transaction, NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList.

If the first expression is an asterisk (*), the transaction will read data until an EOF is encountered. Read to end is supported only for:

• From File

• From String

• From StdIn

• Execute Program

Only the first dimension can have an asterisk rather than a number.

For example, the following transaction reading from a file:

READ TEXT a REAL ARRAY:*,10

will read until EOF is encountered resulting in a two dimensional array with ten columns. The number of rows is dependent on the amount of data in the file. The total number of data elements read must be evenly divisible by the product of the known dimension sizes, in this example: 10. If this criteria is not met, an error will occur.

Number of Characters Per READ

These READ TEXT formats support a choice between DEFAULT NUM CHARS and MAX NUM CHARS:

STRING

INT16

INT32

INT64

BOOLEAN

OCTAL

HEX

REAL32

REAL64

This section discusses the effects of DEFAULT NUM CHARS and MAX NUM CHARS on these formats.

The basic difference between DEFAULT NUM CHARS and MAX NUM CHARS is this:

• DEFAULT NUM CHARS causes VEE to read and ignore most characters that do not appear to be part of the number or string it expects.

• MAX NUM CHARS allows you to read up to the specified number of 8-bit characters in an attempt to build the type of number or string specified. VEE stops reading characters as soon as the READ is satisfied. All characters are read and VEE attempts to convert them to the data type specified in the transaction.

If you specify DEFAULT NUM CHARS, the transaction reads as many characters as it requires to fill each variable. Characters that are not meaningful to the specified data type are read and ignored.

If you specify MAX NUM CHARS, VEE makes no attempt to sort out characters that are not meaningful to the data type specified. If non-meaningful characters are encountered, they are read and may later generate an error.

In either case, newline and end-of-file are recognized as terminators for strings or numbers. For numeric formats, white space encountered before any significant characters (digits) is read and ignored. After reading significant characters, white space or other non-numeric characters terminate the current READ. These are the general behaviors. Read the examples that follow for additional detail.

Consider this example that distinguishes between the behaviors of DEFAULT NUM CHARS and MAX NUM CHARS using INT32 format. Assume you are trying to read a file containing this data:

bird dog cat 12345 horse

It is impossible to extract the integer 12345 from this data with a READ TEXT INT32 transaction using MAX NUM CHARS no matter how many characters are read. This is because the characters bird dog cat are always read before the digits, they cannot be converted to an Integer and this generates an error.

DEFAULT NUM CHARS will extract the integer 12345 by reading and ignoring bird dog cat and treating the white space following 5 as a delimiter.

Effects of Quoted Strings

The presence of quoted strings affects the behavior of READ TEXT QSTR and READ TEXT TOKEN for all I/O paths and READ TEXT STRING for instrument or interface I/O. In this discussion, a quoted string means a set of characters beginning and ending with a double quote character and no embedded (non-escaped) double quote characters. The double quote character is ASCII 34 decimal. The presence of double quotes affects the way that these READ transactions group characters into strings and tokens and how embedded control and escape characters are handled.

In this discussion, the terms control character and escape character have specific meaning. A control character is a single byte of data corresponding to one of the ASCII characters 0-31 decimal. For example, linefeed is ASCII 10 decimal and the symbol <LF> denotes linefeed character in this discussion. The string \n is a human-readable escape character representing linefeed that is recognized by VEE.

The behavior of certain transactions when dealing with quoted strings is dependent on the particular I/O path. For all I/O paths except instrument I/O, READ TEXT QSTR treats quoted strings specially. For all I/O paths except instrument I/O, READ TEXT STRING does not recognize quoted strings.

For instrument I/O there is no READ TEXT QSTR transaction. Instead, READ TEXT STRING recognizes quoted stings and deals with them accordingly. This is done since quoted strings have special meaning in the IEEE 488.2 specification. For all I/O paths including instruments, READ TEXT TOKEN treats quoted strings specially. In the following discussions, we will assume the I/O path to be file I/O.

When a string does not begin and end with double quotes, control characters other than linefeed are read and discarded by READ TEXT STRING transactions and by READ TEXT TOKEN transactions that specify SPACE DELIM. In both STRING and TOKEN transactions, linefeed terminates the READ. Escape character sequences, such as \n (newline) are simply read as the two characters \ and n.

Within double quoted strings, READ TEXT QSTR and READ TEXT TOKEN will read all enclosed characters (including control characters) and store them in the input variable. Embedded linefeeds are read and treated like any other character - they do not terminate the current READ. Escape character sequences are read and translated to their single-character counterpart.

Grouping effects are best explained by using an example. For the discussion in the rest of this section, the data being read is a file with the contents shown below.

"This is in quotes." This is not.

Assume that you read the file above using From File with these transactions:

READ TEXT x QSTR

READ TEXT y QSTR

After reading the file, the results are:

x = This is in quotes.

y = This is not.

The double quotes are interpreted as delimiters and do not appear in the input variable.

Now assume that you read the file above using From File with these transactions:

READ TEXT x QSTR MAXFW:4

READ TEXT y QSTR

After reading the file, the results are:

x = This

y = This is not.

Here the double quotes are still acting a delimiters. The first transaction reads from double quote to double quote and assigns the first four characters to x. This leaves the file's read pointer positioned before the second occurrence of This. The second transaction reads the same string as before.

Next, assume that you read the file above using From File with these transactions:

READ TEXT x TOKEN

READ TEXT y QSTR

After reading the file, the results are:

x = This is in quotes.

y = This is not.

Here, the double quotes effectively make the entire first sentence into a single token. Even though default TOKEN delimiter is white space, the entire quoted string is treated as a single token. In addition, TOKEN reads and discards the double quote characters.


CHAR Format

READ TEXT CHAR transactions are of this form:

READ TEXT VarList CHAR:NumChar ARRAY:NumStr

VarList is a single Text variable or a comma-separated list of Text variables.

NumChar specifies the number of 8-bit characters that must read to fill each element of each variable in VarList.

NumStr is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction.

ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

CHAR format is useful when you wish to simply read one character at a time, or when you need to read every character without ignoring any incoming data.

This transaction reads two two-dimensional Text arrays. Each element in each array contains two characters.

READ TEXT X,Y CHAR:2 ARRAY:2,2

If a file read by the previous transaction contains these characters:

<space>ABCDEFG"AB"<LF>'CD

the variables X and Y contain these values after the READ:

X [0 0] = <space>A

X [0 1] = BC

X [1 0] = DE

X [1 1] = FG

Y [0 0] = "A

Y [0 1] = B"

Y [1 0] = <LF>'

Y [1 1] = CD

The symbol <space> means the single character, space (ASCII 32 decimal). The symbol <LF> means the single character, linefeed (ASCII 10 decimal). Space, linefeed and double quotes are read without any special consideration or interpretation.

See Also

TEXT Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, IOSTATUS Encoding,

REGISTER Encoding, MEMORY Encoding


TOKEN Format

READ TEXT TOKEN transactions are of this form:

READ TEXT VarList TOKEN Delimiter ARRAY:NumElements

VarList is a single Text variable or a comma-separated list of Text variables.

Delimiter specifies the combinations of characters that terminate (delimit) each token.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

TOKEN format allows you to define the delimiter (boundary) for tokens using one of these choices for Delimiter:

• SPACE DELIM

• INCLUDE CHARS

• EXCLUDE CHARS

The following discussion of delimiters explains how the choice of delimiters affects reading a file ( file1) with the contents shown below:

A phrase.
"A phrase."
Tab follows.
XOXXOOXXXOOOXXXX
XAXXBCXXXDEF

The file contains only the letter O, not the digit zero.

There is an invisible linefeed character at the end of each of the first four lines of the file above that shows the file as it would appear in a text editor such as vi.

SPACE DELIM

If you use SPACE DELIM, tokens are terminated by any white space. White space includes spaces, tabs, newline and end-of-file. This corresponds roughly to words in written English. Using SPACE DELIM, you could read a file containing a paragraph of text and separate out individual words.

Double quoted strings receive special treatment. Double quoted strings are read as a single token and the double quotes are stripped away. Control characters (ASCII 0-31 decimal) embedded in double-quoted strings are returned in the output variable. Escape characters (such as \n) embedded in double-quoted strings are converted into their equivalent control characters.

This special treatment of double-quoted strings applies only to SPACE DELIM transactions. INCLUDE CHARS and EXCLUDE CHARS treat double quotes, escapes and control characters the same as any other character.

If you read the data in file1 using SPACE DELIM with this transaction:

READ TEXT a TOKEN ARRAY:8

the variable a contains these values:

a[0] = A

a[1] = phrase.

a[2] = A phrase.

a[3] = Tab

a[4] = follows

a[5] = .

a[6] = XOXXOOXXXOOOXXXX

a[7] = XAXXBCXXXDEF

INCLUDE CHARS

If you use INCLUDE CHARS, you can specify a list of characters to be "included" in tokens returned by the READ. These specified characters will be the only characters returned in any token. Any character other than the specified INCLUDE characters terminates the current token. The terminating characters are not included in the token and are stripped away.

If VEE reads the data in file1 using INCLUDE CHARS with this transaction:

READ TEXT a TOKEN INCLUDE:"X" ARRAY:7

the variable a contains these values:

a[0] = X

a[1] = XX

a[2] = XXX

a[3] = XXXX

a[4] = X

a[5] = XX

a[6] = XXX

If VEE reads the data in file1 using INCLUDE CHARS with this transaction:

READ TEXT a TOKEN INCLUDE:"OXZ" ARRAY:4

the variable a contains these values:

a[0] = XOXXOOXXXOOOXXXX

a[1] = X

a[2] = XX

a[3] = XXX

The first character in the INCLUDE list is the letter O, not the digit zero.

Assume that you are trying to read a file ( file2 )containing the data as follows.

111 222 333 444 555

If you try to read data in the file2 using this transaction:

READ TEXT x,y,z TOKEN INCLUDE:"1234567890"

the Text variables x, y and z will contain these values:

x = 111

y = 222

z = 333

Another way to do this is to specify an ARRAY greater than one and read data into an array. For example, if you read the data above using this transaction:

READ TEXT x TOKEN INCLUDE:"1234567890" ARRAY:3

the Text variable x contains these values:

x[0] = 111

x[1] = 222

x[2] = 333

EXCLUDE CHARS

If you use EXCLUDE CHARS, you can specify a list of characters, any one of which will terminate the current token. The terminating characters are not included in the token. They are read and discarded.

If you read the data in file1 using EXCLUDE with this transaction:

READ TEXT a TOKEN EXCLUDE:"X" ARRAY:8

the variable a contains these values:

a[0] = A phrase.<LF>"A phrase."<LF>Tab follows .<LF>

a[1] = O

a[2] = OO

a[3] = OOO

a[4] = <LF>

a[5] = A

a[6] = BC

a[7] = DEF<LF>

Assume the data below is sent to VEE from an instrument.

++1.23++4.98++0.45++2.34++0.01++23.45++12.2++

If VEE reads the data above with this transaction:

READ TEXT x TOKEN EXCLUDE:"+" ARRAY:7

the variable x will contain these values:

x[0] = null string (empty)

x[1] = 1.23

x[2] = 4.98

x[3] = 0.45

x[4] = 2.34

x[5] = 0.01

x[6] = 23.45

Even though seven "numbers" were available, only six were read. At the end of this transaction, VEE has read seven tokens terminated by the +, including the first character which was terminated before it was filled with any data.

note

The behavior of EXCLUDE CHARS is different between VEE 5 Execution Mode and later and VEE 4 Execution Mode and earlier. See READ TEXT Transactions for a description of this difference.


STRING Format

READ TEXT STRING transactions are of this form:

READ TEXT VarList STR ARRAY:NumElements

-or-

READ TEXT VarList STR MAXFW:NumChars ARRAY:NumElements

VarList is a single Text variable or a comma-separated list of Text variables.

NumChars specifies the maximum number of 8-bit characters that can be read in an attempt to build a string.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

This transaction reads all incoming characters and returns strings. Leading spaces are deleted. The following discussion pertains to instrument I/O paths only, such as GPIB or VXI. All other I/O paths, such as files or name12-pipes, will not treat Quoted Strings specially. See Effects of Quoted Strings for details about the effects of double quoted strings on READ TEXT STRING.

Effects of Control and Escape Characters

In this discussion, the terms control character and escape character have specific meaning. A control character is a single byte of data corresponding to one of the ASCII characters 0-31 decimal. For example, linefeed is ASCII 10 decimal and the symbol <LF> denotes linefeed character in this discussion. The string \n is a human-readable escape character representing linefeed that is recognized by VEE. VEE uses escape characters to represent control characters within quoted strings.

Control characters and escape characters are handled differently depending on whether or not they appear within double quoted strings.

Outside double quoted strings, control characters other than linefeed are read and discarded. Linefeed terminates the current string. Escape characters, such as \n, are read as two individual characters (\ and n).

Within double quoted strings, control characters and escape characters are read and included in the string returned by the READ. A linefeed within a double quoted string does not terminate the current string. Escape characters, such as \n, are interpreted as their single character equivalent (<LF>) and are included in the returned string as a control character.

Assume you want to read the following string data using READ TEXT STRING transactions:

Simple string.

Random \n % $ * ‘A'

"In quotes."

"In quotes

with control."

"In quotes\nwith escape."

  • If you read the string data using this transaction:

READ TEXT x STR ARRAY:5

the variable x contains these values:

a[0] = Simple string.

a[1] = Random \n % $ * ‘A'

a[2] = In quotes.

a[3] = In quotes<LF>with control.

a[4] = In quotes<LF>with escape.

  • If you read the same string data using this transaction:

READ TEXT x STR MAXFW:16 ARRAY:5

the variable x contains these values:

a[0] = Simple string.

a[1] = Random \n % $ *

a[2] = ‘A'

a[3] = In quotes.

a[4] = In quotes<LF>with c

The transaction terminates the current READ whenever 16 characters have been read (a[1]) or when a non-quoted <LF> (a[2]) is read. Double-quoted strings are read from double quote to double quote and the first 16 delimited characters are returned (a[4]).


QUOTED STRING Format

READ TEXT QUOTED STRING transactions are of this form:

READ TEXT VarList QSTR ARRAY:NumElements

-or-

READ TEXT VarList QSTR MAXFW:NumChars ARRAY:NumElements

VarList is a single Text variable or a comma-separated list of Text variables.

NumChars specifies the maximum number of 8-bit characters that can be read in an attempt to build a string.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

This transaction reads all incoming characters and returns strings. The following discussion pertains to all non-instrument I/O paths. Instrument I/O paths do not implement the READ TEXT QSTR transaction. See Effects of Quoted Strings" for details about the effects of double quoted strings on READ TEXT STRING.

See Also

Effects of Control and Escape Characters


INT16 and INT32 Formats

INTEGER Formats

READ TEXT INTEGER transactions are of this form:

READ TEXT VarList INT16(or INT32, INT64, WORD, BYTE) ARRAY:NumElements

-or-

READ TEXT VarList INT16(or INT32, INT64, WORD, BYTE) MAXFW:NumChars ARRAY:NumElements

VarList is a single Integer variable or a comma-separated list of Integer variables.

NumChars specifies the maximum number of 8-bit characters that can be read in an attempt to build a number.

NumStr is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

READ TEXT BYTE transactions interpret incoming characters as 8-bit, two's complement unsigned integers. The valid range for these integers is +255 to 0. Any numbers outside this range generate an error.

READ TEXT WORD transactions interpret incoming characters as 8-bit, two's complement unsigned integers. The valid range for these integers is +65535 to 0. Any numbers outside this range generate an error.

READ TEXT INT16 transactions interpret incoming characters as 16-bit, two's complement integers. The valid range for these integers is 32767 to -32768. Any numbers outside this range generate an error.

READ TEXT INT32 transactions interpret incoming characters as 32-bit, two's complement integers. The valid range for these integers is 2 147 483 647 to -2 147 483 648. Any numbers outside this range generate an error.

READ TEXT INT64 transactions interpret incoming characters as 64-bit, two's complement integers. The valid range for these integers is -9223372036854775808 to +9223372036854775807. Any numbers outside this range generate an error.

As it starts to build a number, VEE discards any leading characters that are not recognized as part of a number. Once VEE starts building a number, any character that is not recognized as part of a number terminates the READ for that number. The following table shows the only combinations of characters that are recognized as part of an integer.

Notation | Characters Recognized
Decimal | Valid characters are ±0123456789. Leading zeros are not interpreted as an octal prefix as they are in VEE data entry fields.
VEE hexadecimal | VEE interprets 0x as a prefix for a hexadecimal number. Valid characters following the prefix are 0123456789aAbBcCdDeEfF.
IEEE 488.2 binary | VEE interprets #b or #B as a prefix for a binary number. Valid characters following the prefix are 0 and 1.
IEEE 488.2 octal | VEE interprets #q or #Q as a prefix for an octal number. Valid characters following the prefix are 01234567.
IEEE 488.2 hexadecimal | VEE interprets #h or #H as a prefix for a hexadecimal number. Valid characters following the prefix are 0123456789aAbBcCdDeEfF.

All the following notations are interpreted as the Integer value 15 decimal:

15

+15

015

0xF

0xf

#b1111

#Q17

#hF


OCTAL Format

READ TEXT OCTAL transactions are of this form:

READ TEXT VarList OCT ARRAY:NumElements

-or-

READ TEXT VarList OCT MAXFW:NumChars

where:

ARRAY:NumElements

VarList is a single Integer variable or a comma-separated list of Integer variables.

NumChars specifies the number of 8-bit characters that can be read in an attempt to build a number.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

READ TEXT OCTAL transactions interpret incoming characters as octal digits representing 64-bit, two's complement integers. The valid range for these integers is -9223372036854775808 to +9223372036854775807decimal.

If the transaction specifies a MAX NUM CHARS (MAXFW), the octal number read may contain more than 64 bits of data. For example, assume VEE reads the following octal data:

37723745621456724377745277234

using this transaction:

READ TEXT x OCT MAXFW:32

VEE reads all the digits in octal data, but uses only the last 22 digits (5621456724377745277234) to build a number for the value of x. This is because each digit corresponds to 3 bits and the octal number must be stored in an VEE Integer, which contains 64 bits. 22 octal digits yield 66 bits and the most 2 significant bits are dropped to fit the value in an VEE Integer. There is no possibility of overflow.

Note

In VEE 6&7 and prior modes, READ TEXT OCTAL transactions interpret incoming characters as octal digits representing 32-bit, two's complement integers. The valid range for these integers is 2 147 483 647 to -2 147 483 648 decimal.

If the transaction specifies DEFAULT NUM CHARS, it will continue to read characters until it builds enough numbers to fill each variable in VarList. Linefeed characters will not terminate number building early. For example, this transaction:

READ TEXT x OCT ARRAY:4

interprets each line of the following octal data as the same set of four octal numbers:

0345 067 003<LF>0377<LF>

345 67 3 377<EOF>

345,67,3,377,45,67<EOF>

The symbol <LF> represents the single character linefeed (ASCII 10 decimal). The symbol <EOF> represents the end-of-file condition.


HEX Format

READ TEXT HEX transactions are of this form:

READ TEXT VarList HEX ARRAY:NumElements

-or-

READ TEXT VarList HEX MAXFW:NumChars ARRAY:NumElements

VarList is a single Integer variable or a comma-separated list of Integer variables.

NumChars specifies the number of 8-bit characters that can be read in an attempt to build a number.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

READ TEXT HEX transactions interpret incoming characters as hexadecimal digits representing 64-bit, two's complement integers. The valid range for these integers is -9223372036854775808 decimal to +9223372036854775807 decimal.

If the transaction specifies a MAX NUM CHARS (MAXFW), the hexadecimal number read may contain more than 64 bits of data. For example, assume VEE reads the following hexadecimal data:

ad2469Ff725BCdef37964 hexadecimal data

using this transaction:

READ TEXT x HEX MAXFW:32

VEE reads all the digits in the hexadecimal data, but uses only the last 16 digits (9Ff725BCdef37964) to build a number for the value of x. This is because each digit corresponds to 4 bits and the hexadecimal number must be stored in an VEE Integer, which contains 64 bits. 16 hexadecimal digits yields exactly 64 bits. There is no possibility of overflow.

Note

In VEE 6&7 and prior modes, READ TEXT HEX transactions interpret incoming characters as octal digits representing 32-bit, two's complement integers. The valid range for these integers is 2 147 483 647 to -2 147 483 648 decimal.

Assume VEE reads the same hexadecimal data, but with a different MAX NUM CHARS, as in this transaction:

READ TEXT x HEX MAXFW:3 ARRAY:7

In this case, the transaction reads the same data and interprets it as seven Integers, each comprising three hexadecimal digits.

If the transaction specifies DEFAULT NUM CHARS, it will continue to read characters until it builds enough numbers to fill each variable in VarList. Each number will read exactly 8 hexadecimal digits. Linefeed characters will not terminate number building early.

Assume VEE reads the same hexadecimal data, but with DEFAULT NUM CHARS, as in this transaction:

READ TEXT x HEX ARRAY:2

In this case, the transaction reads the same data and interprets it as two Integers, each comprising eight hexadecimal digits. The last five digits (37946) are not read.


REAL32 and REAL64 Format

READ TEXT REAL32 and READ TEXT REAL64 transactions are of this form:

READ TEXT VarList REAL32(or REAL64) ARRAY:NumElements

-or-

READ TEXT VarList REAL32(or REAL64) MAXFW:NumChars ARRAY:NumElements

VarList is a single Real variable or a comma-separated list of Real variables.

NumChars specifies the maximum number of 8-bit characters that can be read in an attempt to build a number.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

The decimal number read by this transaction is interpreted as a VEE Real32, which is a 32-bit IEEE 754 floating-point number. The range of these numbers is:

-1.175 494 35E-38

-3.402 823 47E+38

to

3.402 823 47E+38

1.175 494 35E-38

The decimal number read by this transaction is interpreted as a VEE Real64, which is a 64-bit IEEE 754 floating-point number. The range of these numbers is:

-1.797 693 134 862 315E+308

-2.225 073 858 507 202E-307

to

2.225 073 858 507 202E-307

1.797 693 134 862 315E+308

If the transaction specifies a MAX NUM CHARS (MAXFW), the Real number read may contain more than 17 digits of data. For example, assume VEE reads the following real data:

1.234567890123456789 real number data

using this transaction:

READ TEXT x REAL64 MAXFW:19

VEE reads all the digits in the real data, but uses only the 17 most-significant digits of the mantissa to build a number for the value of x. This is because each Real contains a 54-bit mantissa, which is equivalent to more than 16 but less than 17 decimal digits. As a result, x has the value 1.2345678901234567.

Text to Real conversions are not guaranteed to yield the same value to the least-significant digit. Comparisons of the two least-significant bits is inadvisable.

Assume VEE reads the same real number data, but with a different MAX NUM CHARS, as in this transaction:

READ TEXT x REAL64 MAXFW:6 ARRAY:3

In this case, the transaction reads the same data and interprets it as 3 Real numbers, each comprised of six decimal characters. The last two characters are not read.

If the transaction specifies DEFAULT NUM CHARS, it will continue to read characters until it builds enough numbers to fill each variable in VarList. Each number will read at most 17 decimal digits. Linefeed characters, white space and other non-numeric characters will terminate number building before 17 digits have been read.

READ TEXT REAL64 and REAL32 transactions recognize most commonly used decimal notations for Real numbers including leading signs, decimal points and signed exponents. The characters +-.0123456789Ee are recognized as valid parts of a Real number by all READ TEXT REAL transactions. If the transaction specifies DEFAULT NUM CHARS, the suffix characters shown in the following table are also recognized. The suffix character must immediately follow the last digit of the number with no intervening white space.

Suffix | Multiplier
P | 1015
T | 1012
G | 109
M | 106
k or K | 103
m | 10-3
u | 10-6
n | 10-9
p | 10-12
f | 10-15

The following Text data represents six real numbers:

1001

+1001.

1001.0

1.001E3

+1.001E+03

1.001K

  • If VEE reads the real text data with this transaction:

READ TEXT x REAL64 ARRAY:6

then each element of the Real variable x contains the value 1001.

  • If VEE reads the same data with this transaction:

READ TEXT x REAL64 MAXFW:20 ARRAY:6

the first five elements of the Real variable x contain the value 1001 and the sixth element contains the value 1.001.


COMPLEX, PCOMPLEX and COORD Formats

COMPLEX, PCOMPLEX and COORD correspond to the VEE multi-field data types with the same names. The behavior of all three READ formats is very similar. The behaviors described in this section apply to all three formats except as noted.

Just as the VEE data types Complex, PComplex and Coord are composed of multiple Real64 numbers, the COMPLEX, PCOMPLEX and COORD formats are compound forms of the REAL64 format. Each constituent Real value of the multi-field data types is read using the same rules that apply to an individual REAL64 formatted value.

COMPLEX Format

READ TEXT COMPLEX transactions are of this form:

READ TEXT VarList CPX ARRAY:NumElements

Each READ TEXT COMPLEX transaction reads the equivalent of two REAL formatted numbers. The first number read is interpreted as the real part and the second number read is interpreted as the imaginary part.

PCOMPLEX Format

READ TEXT PCOMPLEX transactions are of this form:

READ TEXT VarList PCX:PUnit ARRAY:NumElements

PUnit specifies the units of angular measure in which the phase of the PComplex is measured.

Each READ TEXT PCOMPLEX transaction reads the equivalent of two REAL formatted numbers. The first number read is interpreted as the magnitude and the second number read is interpreted as the phase.

If any transaction reading COMPLEX, PCOMPLEX, or COORD formats encounters an opening parenthesis, it expects to find a closing parenthesis.

Assume you want to read a file containing the following data containing parentheses:

(1.23 , 3.45 (6.78 , 9.01) (1.23 , 4.56)

If VEE reads the data with this transaction:

READ TEXT x,y CPX

the variables x and y contain these Complex values:

x = (1.23 , 3.45)

y = (1.23 , 4.56)

The transaction read past 6.78 and 9.01 to find the closing parenthesis. If parentheses had been omitted from the data entirely, y would have the value (6.78 , 9.01).

COORD Format

READ TEXT COORD transactions are of this form:

READ TEXT VarList COORD:NumFields ARRAY:NumElements

VarList is a single Coord variable or a comma-separated list of Coord variables.

NumFields is a single variable or expression that specifies the number of rectangular dimensions in each Coord value. This value must be 2 or more for the READ to execute without error.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.


BINARY Encoding

READ BINARY transactions are of this form:

READ BINARY VarList DataType ARRAY:NumElements

VarList is a single variable or a comma-separated list of variables.

DataType is one of the following pre-defined formats corresponding to the VEE data type with the same name:

• Boolean - 32-bit two's complement integer

• BYTE - 8-bit unsigned byte

• WORD - 16-bit unsigned integer

• INT16 - 16-bit two's complement integer

• INT32 - 32-bit two's complement integer

• INT64 - 64-bit two's complement integer

• REAL32 - 32-bit IEEE 754 floating-point number

• REAL64 - 64-bit IEEE 754 floating-point number

• STRING - null terminated string

• COMPLEX - equivalent to two REAL64s

• PCOMPLEX -equivalent to two REAL64s

• COORD - equivalent to two or more REAL64s

note

VEE 5 and lower Execution Modes store and manipulate all integer values as the INT32 data type and all real numbers as the Real data type, also known as REAL64. Thus, the INT16 and REAL32 data types are provided for I/O only. VEE 5 and lower Execution Modes perform the following data-type conversions for instrument I/O on an input transaction.

INT16 values from an instrument are individually converted to INT32 values by VEE 5 and lower Execution Modes. This conversion assumes that the INT16 data was signed data. If you need the resulting INT32 data in unsigned form, pass the data through a formula object with the formula

BITAND(a, 0xFFFF)

REAL32 values from an instrument are individually converted to REAL64 values by VEE 5 and lower.

VEE 6 Execution Mode retains the data type.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the first expression is an asterisk (*), the transaction will read data until an EOF is encountered. Read to end is supported only for:

  • From File

  • From String

  • From StdIn

  • Execute Program

Only the first dimension can have an asterisk rather than a number. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

For example, the following transaction, reading from a file:

READ BINARY a REAL64 ARRAY:*,10

will read until EOF is encountered, resulting in a two dimensional array with 10 columns. The number of rows is dependent on the amount of data in the file. The total number of data elements read must be evenly divisible by the product of the known dimension sizes, in this example: 10.

READ BINARY transactions expect that incoming data is in exactly the same format that would be produced by an equivalent WRITE BINARY transaction. BINARY encoded data has the advantage of being very compact, but it is not easily shared with non-VEE applications.

See Also

TEXT Encoding, BINBLOCK Encoding, CONTAINER Encoding, IOSTATUS Encoding,

REGISTER Encoding, MEMORY Encoding


BINBLOCK Encoding

READ BINBLOCK transactions are of this form:

READ BINBLOCK VarList DataType ARRAY:NumElements

VarList is a single variable or a comma-separated list of variables.

DataType is one of these pre-defined VEE data types:

• Boolean - 32-bit two's complement integer

• BYTE - 8-bit unsigned byte

• WORD - 16-bit unsigned integer

• INT16 - 16-bit two's complement integer

• INT32 - 32-bit two's complement integer

• INT64 - 64-bit two's complement integer

• REAL32 - 32-bit IEEE 754 floating-point number

• REAL64 - 64-bit IEEE 754 floating-point number

• STRING - null terminated string

• COMPLEX - equivalent to two REAL64s

• PCOMPLEX -equivalent to two REAL64s

• COORD - equivalent to two or more REAL64s

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. The number of columns is equal to the number of channels contained by the binblock. The number of rows is equal to the number of readings per channel. Only the first dimension can have an asterisk rather than a number.

If the first expression is an asterisk (*), the transaction will read data until an EOF is encountered. Read to end is supported only for:

  • From File

  • From String

  • From StdIn

  • Execute Program

If the transaction is configured to read a one-dimension array, for a single channel, the single dimension represents rows and can have an asterisk.

For example, the following transaction, reading from a file:

READ BINBLOCK a REAL64 ARRAY:*,10

will read until EOF is encountered, resulting in a two-dimensional array with 10 columns. Each column represents an instrument channel. The number of rows is dependent on the amount of data in each channel. The total number of data elements contained by the binblock must be evenly divisible by the number of columns, in this example: 10.

You do not need to specify any additional information about the format of incoming data as the block header contains sufficient information. READ BINBLOCK can read any of the block formats described previously with WRITE BINBLOCK transactions.

The following transaction reads two traces from an oscilloscope that formats its traces as IEEE 488.2 Definite Length Arbitrary Block Response Data:

READ BINBLOCK a,b REAL64

See Also

TEXT Encoding, BINARY Encoding, CONTAINER Encoding, IOSTATUS Encoding,

REGISTER Encoding, MEMORY Encoding


CONTAINER Encoding

READ CONTAINER transactions are of the form:

READ CONTAINER VarList

VarList is a single variable or a comma-separated list of variables.

READ CONTAINER transactions reads data stored in the special text representation written by WRITE CONTAINER transactions. No additional specifications, such as format, needs to be specified with READ CONTAINER since that information is part of the container.

See Also

TEXT Encoding, BINARY Encoding, BINBLOCK Encoding, IOSTATUS Encoding,

REGISTER Encoding, MEMORY Encoding


REGISTER Encoding

READ REGISTER is used to read values from a VXI instrument's A16 memory.

READ REGISTER transactions are of this form:

READ REG: SymbolicName ExpressionList INCR ARRAY:NumElements

-or-

READ REG: SymbolicName ExpressionList ARRAY:NumElements

where:

SymbolicName is a name defined during configuration of a VXI instrument. The name refers to a specific address within a instrument's register space. Specific data types for READ REGISTER transactions are:

BYTE - 8 bit unsigned byte

WORD16 - 16-bit two's complement integer

WORD32 - 32-bit two's complement integer

REAL32 - 32-bit IEEE 754 floating point number

These data types are also specified during configuration of a VXI instrument and do not appear in the transaction.

ExpressionList is a single expression or a comma-separated list of expressions.

INCR specifies that array data is to be read from the register incrementally starting at the address specified by SymbolicName. The first element of the array is read from the starting address, the second from that address plus an offset equal to the length in bytes of the data type, etc. until all array elements have been read. If INCR is not specified in the transaction, the entire array is read from the single location specified by SymbolicName.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

See Also

TEXT Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, IOSTATUS Encoding,

MEMORY Encoding


MEMORY Encoding

READ MEMORY is used to read values from a VXI instrument's A24 or A32 memory.

READ MEMORY transactions are of this form:

READ MEM: SymbolicName ExpressionList INCR ARRAY:NumElements

-or-

READ MEM: SymbolicName ExpressionList ARRAY:NumElements

where:

SymbolicName is a name defined during configuration of a VXI instrument. The name refers to a specific address within a instrument's extended memory. Specific data types for READ MEMORY transactions are:

• BYTE - 8 bit unsigned byte

• WORD16 - 16-bit two's complement integer

• WORD32 - 32-bit two's complement integer

• REAL32 - 32-bit IEEE 754 floating point number

• WORD32*2 - two 32-bit two’s complement integers in adjacent elements of an Int32 array

REAL64 - 64-bit IEEE 754 floating point number.

These data types are also specified during configuration of a VXI instrument and do not appear in the transaction.

ExpressionList is a single expression or a comma-separated list of expressions.

INCR specifies that array data is to be read from the memory location incrementally starting at the location specified by SymbolicName. The first element of the array is read from the starting location, the second from that location plus an offset equal to the length in bytes of the data type, etc. until all array elements have been read. If INCR is not specified in the transaction, the entire array is read from the single memory location specified by SymbolicName.

NumElements is a single expression or a comma-separated list of expressions that specifies the dimensions of each variable in VarList. If the transaction is configured to read a scalar, the ARRAY keyword does not appear in the transaction. ARRAY:1 is a one-dimensional array with one element. VEE makes a distinction between scalars and one-dimensional arrays containing only one element.

See Also

TEXT Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding, IOSTATUS Encoding,

REGISTER Encoding


IOSTATUS Encoding

READ IOSTATUS transactions are of this form:

READ IOSTATUS STS Bits VarList

-or-

READ IOSTATUS DATA READY VarList

VarList is a single Integer variable or a comma-separated list of Integer variables.

READ IOSTATUS transactions are used by Direct I/O for GPIO interfaces, From StdIn, and To/From Named Pipe.

READ IOSTATUS transactions for GPIO reads the peripheral status bits available on the interface. The number of bits read is dependent on the model number of the interface. A single integer value is returned that is the weighted sum of all the status bits.

For example, the HP 98622A GPIO interface supports two peripheral status lines, STI0 and STI1. The following table illustrates how to interpret the value of x in this transaction:

READ IOSTATUS STS Bits a

Value Read | STI1 | STI0
0 | 0 | 0
1 | 0 | 1
2 | 1 | 0
3 | 1 | 1

READ IOSTATUS transactions read the instantaneous values of the status lines; the status line are not latched or buffered in any way.

READ IOSTATUS transactions return a Boolean YES (1) if there is data ready to read. If no data is present, a Boolean NO (0) is returned. The READ IOSTATUS transaction can be used to avoid a READ that will block program execution until data is available.

See Also

TEXT Encoding, BINARY Encoding, BINBLOCK Encoding, CONTAINER Encoding,

REGISTER Encoding, MEMORY Encoding


EXECUTE Transactions

EXECUTE transactions send low-level commands to control the file, instrument, or interface associated with a particular object. EXECUTE is used to adjust file pointers, clear buffers and provide low-level control of hardware interfaces. The various EXECUTE commands available are summarized below.

Commands

Description

To File, From File

REWIND

Sets the read pointer (From File) or write pointer (To File) to the beginning of the file without changing the data in the file.

CLEAR

(To File only). Erases existing data in the file and sets the write pointer to the beginning of the file.

CLOSE

Explicitly closes the file. Useful when multiple processes are reading and writing the same file.

DELETE

Explicitly deletes the file. Useful for deleting temporary files.

Interface Operations

CLEAR

For GPIB, clears all instruments by sending DCL (Device Clear). For VXI, resets the interface and runs the resource manager

TRIGGER

For GPIB, triggers all instruments addressed to listen by sending GET (Group Execute Trigger). For VXI triggers specified backplane trigger lines or external triggers on an embedded controller.

LOCAL

For GPIB, releases the REN (Remote Enable) line and puts instrument into local mode.

REMOTE

For GPIB, asserts the REN (Remote Enable) line.

LOCAL LOCKOUT

For GPIB, sends the LLO (Local Lockout) message. Any instrument in remote at the time LLO is sent will lock out front panel operation.

ABORT

Clears the GPIB interface by asserting the IFC (Interface Clear) line.

LOCK INTERFACE

In a multiprocess system with shared resources, lets one process lock the resources for its own use during a critical section to prevent another process from trying to use them.

UNLOCK INTERFACE

In a multiprocess system where a process has locked shared resources for its own use, unlocks the resources to allow other processes access to them.

Direct I/O to GPIB

CLEAR

Clears instrument at the address of a Direct I/O object by sending the SDC (Selected Device Clear).

TRIGGER

Triggers the instrument at the address of a Direct
I/O object by addressing it to listen and sending GET
(Group Execute Trigger).

LOCAL

Places the instrument at the address of the Direct
I/O object in the local state.

REMOTE

Places the instrument at the address of the Direct
I/O object in the remote state.

Direct I/O to GPIO

RESET

Resets the GPIO interface associated with the Direct I/O object by pulsing the PRESET line (Peripheral Reset).

Direct I/O to message-based VXI

CLEAR

Clears the VXI instrument associated with the Direct I/O object by sending the word-serial command Clear (0xffff).

TRIGGER

Triggers the VXI instrument associated with the Direct
I/O object by sending the word-serial command Trigger (0xedff).

LOCAL

Places the VXI instrument associated with the Direct I/O object into local state by sending the word-serial command Clear Lock (0xefff).

REMOTE

Places the VXI instrument associated with the Direct I/O object into local state by sending the word-serial command Set Lock (0xeeff). in the remote state.

Direct I/O to Serial Interfaces

RESET

Resets the serial interface associated with the Direct I/O object.

BREAK

Transmits a signal on the Data Out line of the serial interface associated with the Direct I/O object as follows:

A logical High for 400 milliseconds

A logical Low for 60 milliseconds

CLOSE

Close the connection with the serial interface associated with the Direct I/O Object. A connection is reestablished at the next connection, if any.

Execute Program, To/From Named Pipe

CLOSE READ PIPE

Closes the read named pipe associated with the (To/From) object or the stdin pipe associated with the (Execute Program).

CLOSE WRITE PIPE

Closes the write named pipe associated with the (To/From) object or the stdout pipe associated with the (Execute Program).

To/From Socket

CLOSE

Closes the connection between client and server sockets. To re-establish the connection, the client and server must repeat the bin12-accept and connect-to protocols.

Direct I/O, MultiInstrument Direct I/O, Interface Operations to GPIB,
VXI, Serial, and GPIO

LOCK

In a multiprocess system with shared resources, lets one process lock the resources for its own use during a critical section to prevent another process from trying to use them.

UNLOCK

In a multiprocess system where a process has locked shared resources for its own use, unlocks the resources to allow other processes access to them.

Details About GPIB

The EXECUTE commands used by Direct I/O to GPIB instruments and Interface Operations are similar but different.

• Direct I/O EXECUTE commands address an instrument to receive the command.

• Interface Operations EXECUTE commands may affect multiple instruments already addressed to listen.

The following 6 tables indicate the exact bus actions conducted by Direct I/O and Interface Operations EXECUTE transactions.

EXECUTE ABORT GPIB Actions

Direct I/O | Interface Operations
Not applicable. | IFC (>=100 µsec)
 | REN
 | ATN

EXECUTE CLEAR GPIB Actions

Direct I/O | Interface Operations
ATN | ATN
MTA | DCL
UNL |
LAG |
SDC |

EXECUTE TRIGGER GPIB Actions

Direct I/O | Interface Operations
ATN | ATN
MTA | GET
UNL |
LAG |
GET |

EXECUTE LOCAL GPIB Actions

Direct I/O | Interface Operations
ATN | REN
MTA | ATN
UNL |
LAG |
GTL |

EXECUTE REMOTE GPIB Actions

Direct I/O | Interface Operations
REN | REN
ATN | ATN
MTA |
UNL |
LAG |

EXECUTE LOCAL LOCKOUT GPIB Actions

Direct I/O | Interface Operations
Not applicable. | ATN
 | LLO

Details About VXI

The EXECUTE commands used by Direct I/O to VXI instruments and Interface Operations are similar, but different. References to message-based VXI instruments apply to register-based instruments that are supported
by I-SCPI.

• Direct I/O EXECUTE commands address a message-based VXI instrument to receive a word-serial command.

• Interface Operations EXECUTE commands affect the VXI interface directly and may affect VXI instruments within the interfaces servant area.

EXECUTE TRIGGER transactions for the Interface Operations object are of the form:

EXECUTE TRIGGER TriggerType Expression TriggerMode

TriggerType specifies which trigger group will be used by the

EXECUTE TRIGGER transaction. The groups are:

• TTL - Specifies the eight TTL trigger lines on the VXI backplane.

• ECL - Specifies the four ECL trigger lines on the VXI backplane.

• EXT - Specifies the external triggers on a embedded VXI controller.

Expression evaluates to a single Integer variable that represents a bit pattern indicating which trigger lines for a particular TriggerType are to be triggered. A value of 5, represented in binary as 101, indicates that TTL lines 0 and 2 are to be triggered. A value of 255 triggers all eight TTL lines. TriggerMode indicates the way the trigger lines are to be asserted:

• PULSE - Lines are to be pulsed for a discreet time limit (TriggerType dependent).

• ON - Asserts the trigger lines and leaves them asserted.

• OFF - Removes the assertion from trigger lines that were asserted by a previous ON transaction.

The following tables indicate the bus actions conducted by Direct I/O and Interface Operations EXECUTE transactions.

EXECUTE CLEAR VXI Actions

Direct I/O | Interface Operations
Word-serial command Clear(0xffff) | Pulse SYSRESET line, rerun Resource Manager

EXECUTE TRIGGER VXI Actions

Direct I/O | Interface Operations
Word-serial command Trigger(0xedff) | Triggers either the TTL or ECL trigger lines in the backplane or the external trigger(s) on the embedded VXI controller. You can specify which lines are to be triggered for each trigger type.

EXECUTE LOCAL VXI Actions

Direct I/O | Interface Operations
Word-serial command Set Lock(0xeeff) | Not applicable.

EXECUTE REMOTE VXI Actions

Direct I/O | Interface Operations
Word-serial command Clear Lock(0xefff) | Not applicable.


WAIT Transactions

There are four types of WAIT transactions:

• WAIT INTERVAL

• WAIT SPOLL (Direct I/O to GPIB and message-based VXI instruments only)

• WAIT REGISTER (Direct I/O to VXI instruments only)

• WAIT MEMORY (Direct I/O to VXI instruments only)

WAIT INTERVAL transactions wait for the specified number of seconds before executing the next transaction listed in the open view of the object. For example, this transaction waits for 10 seconds:

WAIT INTERVAL:10

WAIT SPOLL transactions are of the form:

WAIT SPOLL Expression Sense

Expression is an expression that evaluates to an integer. The integer will be used as a bit mask.

Sense is a field with two possible values.

• ANY SET

• ALL CLEAR

WAIT SPOLL transactions wait until the serial poll response byte of the associated instrument meets a specific condition. The serial poll response is tested by bitwise ANDing it with the specified mask and ORing the resulting bits into a single test bit. The transaction following WAIT SPOLL executes when one of the following conditions is met:

• The transaction specifies ANY (ANY SET) and the test bit is true (1).

• The transaction specifies CLEAR (ALL CLEAR) and the test bit is false (0).

The following transactions show one way to use WAIT SPOLL:

WAIT SPOLL:256 ANY Wait until any bit is set.

WAIT SPOLL:256 CLEAR Wait until all are clear.

WAIT SPOLL:0x40 ANY Wait until bit 6 is set.

WAIT SPOLL:0x40 CLEAR Wait until bit 6 is clear.

WAIT REGISTER and WAIT MEMORY transactions are of the form:

WAIT REG:SymbolicName MASK:Expression Sense [Expression]

-or-

WAIT MEM:SymbolicName MASK:Expression Sense [Expression]

where:

SymbolicName is a name defined during configuration of a VXI instrument. The name refers to a specific address within a instrument's A16 or extended memory.

MASK:Expression is an expression that evaluates to an integer. The integer will be used as a bit mask. The size in bytes of this mask value depends on the data type for which SymbolicName has been configured.

Sense is a field with three possible values.

• ANY SET

• ALL CLEAR

• *EQUAL

[Expression] is an optional compare value that evaluates to an integer. The integer is used only when Sense is EQUAL.

WAIT REGISTER or MEMORY transactions wait until the value read from the register or memory location specified by SymbolicNames in the associated VXI instrument meets a certain condition.

The value read is logically ANDed with the bit mask specified in MASK:Expression, resulting in a test value. The size of the test value is dependent on the data type configured for the specified register or memory location. The transaction following WAIT SPOLL executes when one of the following conditions is met:

• The transaction specifies ANY (ANY SET) and the test value has at least one bit true (1).

• The transaction specifies CLEAR (ALL CLEAR) and the test value has all bits false (0).

• The transaction specifies EQUAL and the test value is equal bit-for-bit with the compare value specified in [Expression].


SEND Transactions

SEND transactions are of this form:

SEND BusCmd

BusCmd is one of the bus commands listed in the following table.

SEND transactions are used within Interface Operations objects to transmit low-level bus messages via a GPIB interface. These messages are defined in detail in IEEE 488.1.

Command | Description
COMMAND | Sets ATN true and transmits the specified data bytes. ATN true indicates that the data represents a bus command.
DATA | Sets ATN false and transmits the specified data bytes. ATN false indicates that the data represents instrument-dependent information.
TALK | Addresses a instrument at the specified primary bus address (0-31) to talk.
LISTEN | Addresses a instrument at the specified primary bus address (0-31) to listen.
SECONDARY | Specifies a secondary bus address following a TALK or LISTEN command. Secondary addresses are typically used by cardcage instruments where the cardcage is at a primary address and each plug-in module is at a secondary address.
UNLISTEN | Forces all instruments to stop listening and sends UNL.
UNTALK | Forces all instruments to stop talking; sends UNT.
MY LISTEN ADDR | Addresses the computer running VEE to listen and sends MLA.
MY TALK ADDR | Addresses the computer running VEE to talk and sends MTA.
MESSAGE | Sends a multi-line bus message. Consult IEEE 488.1 for details. The multi-line messages are: DCL Device Clear SDC Selected Device Clear GET Group Execute Trigger GTL Go To Local3 LLO Local Lockout SPE Serial Poll Enable SPD Serial Poll Disable TCT Take Control


WRITE(POKE) Transactions

The WRITE(POKE) transaction is very similar to the WRITE transaction, except that it applies only to the To/From DDE object. The main difference of WRITE(POKE) is that you must specify an item name. For example:

WRITE ITEM:"r2c3" TEXT a EOL

The following encodings are allowed:

• TEXT

• BYTE

• CASE

• CONTAINER

For more specific information about these formats see the WRITE transaction.


READ(REQUEST) Transactions

The READ(REQUEST) transaction is very similar to the READ transaction, except that it applies only to the To/From DDE object. The main difference of READ(REQUEST) is that you must specify an item name. For example:

READ ITEM:"r2c3" TEXT a EOL

READ(REQUEST) transactions are supported by VEE for Windows only.

The following encodings are allowed:

• TEXT

• CONTAINER

For more specific information about these formats see the READ transaction.


To Visit VEE on the World Wide Web

To Visit Agilent VEE Pro on the World Wide Web

The VEE Web site is packed with helpful resources. To visit us, see the Help menu in VEE:

Help [image] Agilent VEE on the Web

VEE Users Group (vrf)
provides a you with a wealth of information gathered through the interaction of thousands of VEE users. You can post questions, search for tips, and find other expert VEE users.

Support
provides a variety of services for downloading drivers and product updates, technical information, and other resources to improve your productivity.

Instrument Drivers
provides a variety of services for downloading drivers. Available drivers include IVI Drivers, VXIplug&play Drivers for HP/Agilent instruments, and Panel Drivers.

Education/Training
provides information on Agilent worldwide education and training.

Agilent VEE Home Page
provides a central location for access to news, information, applications, and other support for VEE.

Agilent Developers Network
provides a variety of services for downloading drivers and product updates, technical information, white papers, and other resources to improve your productivity.

Agilent Technologies Home Page
provides access to news and information about Agilent Technologies with links to other sites providing measurement and analysis solutions.

The Agilent Home Page is:

http://www.agilent.com

The VEE Home Page is:

http://www.agilent.com/find/vee


To Get Support and Download Instrument Drivers

To Download Instrument Drivers

You can get Complimentary Startup Support from the VEE Support Web site.

To visit the VEE Support Web site, see the Help menu in VEE:

Help [image] Agilent VEE on the Web [image] Support

-and-

You can download drivers from http://www.agilent.com/find/adn

This is a free service from Agilent that offers 24/7 access to drivers, white papers, and other free services.


Call Centers

Designated locations provide support for major regions of the world. These Call Centers offer Complimentary Startup Assistance, online technical support, information, and sales assistance. Please call the phone number listed for your region.

Contacts can be found on the Web site:

http://www.agilent.com/find/assist


About the VEE Pro RunTime Product

The VEE Pro RunTime product provides an environment to run VEE programs, and is separate from the VEE Pro development environment. You cannot develop programs with VEE Pro RunTime. You create, test, debug, and save VEE programs with a VEE development environment. Then, you install VEE Pro RunTime on the systems that will run the VEE programs; for example, to control processes or operate test systems. Operators can use the VEE programs, but they cannot modify them. They see the programs only in their panel views.

In most situations, you develop a VEE program to help people test or monitor something. The system that runs a VEE program will typically need interface cards that interact with instruments. While a VEE program can be developed "without documentation," you should know which interface cards are required for the program to work in a run-time context, and you should provide necessary information to the people who will use the program. (If you have questions about supported interface cards, see your Agilent Technologies sales representative.)

Besides interface cards, the system that runs a VEE program might need the Agilent I/O Libraries Suite (Version 15.0 or higher). For more information about controlling instruments, see Control Instruments.

The VEE Pro RunTime product ships on the same CD-ROM that contains the VEE Pro development environment. When you run setup.exe from your VEE Pro CD, you can choose to install VEE Pro RunTime or the VEE Pro development environment.

Distributing a VEE Program

For topics describing techniques to develop VEE programs for distribution, see VEE Help under the heading How Do I … Build an Operator Interface. Under the heading, Preparing a Program for Distribution to Others, see the topics under Creating a Distribution Package. For specific information about moving a program to run on another system see To Include All Needed Files.

Very Important

The version of VEE Pro RunTime used to run a program must be the same or newer than the version of VEE used to develop the program.

The version of the Agilent I/O Libraries must be compatible with the version of the VEE Pro development environment used to develop your program, and with VEE Pro RunTime. (For VEE 8.5 you need Agilent I/O Libraries Suite version 15.0 or higher.) To ensure this compatibility, use the Agilent I/O Libraries that is shipped with VEE. If you upgrade VEE using downloadable patches from our Web site, be sure to verify the Agilent I/O Libraries compatibility.

Note

Agilent VEE Pro licensees are allowed unlimited installation and distribution rights for VEE Pro RunTime and the Agilent I/O Libraries that are included with the VEE Pro product. You may install VEE Pro RunTime and the Agilent I/O Libraries on systems inside and outside your company when you distribute your VEE programs.

See Also

For VEE Pro RunTime system requirements, see System Requirements for VEE Pro RunTime. For installation instructions, see To Install VEE Pro RunTime. For configuration instructions, see To Configure VEE Pro RunTime.


System Requirements for VEE Pro RunTime

The minimum system requirements for VEE Pro RunTime are:

.NET Framework 2.0

PC with a Pentium 120 MHz processor (266 MHz Pentium II or higher recommended)

Windows Vista (32-bit only, Business, Ultimate, and Enterprise), Windows 2000(SP4), or Windows XP(SP2) operating system

48 MB RAM with Windows 2000/ Windows XP

Hard disk free space: 70 MB minimum (105 MB with MATLAB and tutorials)

CD-ROM drive

15-inch monitor 800x600 Super VGA (17-inch 1024x768 Ultra VGA or larger recommended)

PC keyboard

2-button mouse (3rd button, if present, is not used)

Desired instruments, interface cards, and other peripherals as needed


To Install VEE Pro RunTime

After developing a VEE program, you may want to run it on other systems. VEE programs are not self-contained .exe files. A version of VEE must be installed on any system that runs VEE programs. Of course, the full VEE Pro development environment can be used to run VEE programs, but VEE Pro RunTime is a more economical alternative for those "run-only" systems.

This topic explains how to install VEE Pro RunTime on a Windows system that does not already have VEE installed.

Note

VEE Pro owners are allowed unlimited installation and distribution rights for the VEE Pro RunTime product. You may install VEE Pro RunTime on systems inside and outside your company when you distribute your VEE programs. You may need to provide installation instructions with your program.

The VEE Pro development environment may be installed on systems as allowed by the VEE Pro Software License Agreement and License to Use.

Be aware that you must have system administrator capability to install VEE Pro RunTime on computers running Windows Vista, Windows XP, or Windows 2000 operating system.

To begin an installation, have Windows running, and stop all applications. Insert the CD-ROM in the CD-ROM drive. Wait for the installation to begin automatically. One of two things can happen:

1. A screen appears on your monitor that lets you install the development environment or the run-time environment.

Select the run-time environment. After this, work through the series of screens that let you install the environment.

2. The CD-ROM installation process does not start automatically. Therefore, you need to run the following command to start the run-time environment installation:

e:\runtime\setup.exe

This assumes the CD-ROM drive is drive E:. To run this command, select the Start button in the Windows taskbar. Then, select Run and type the command.


To Configure VEE Pro RunTime

The run-time environment is intended to run programs, not develop them. Therefore, the main VEE window and workspace are not accessible on systems that have only VEE Pro RunTime installed. Characteristics of the VEE environment that are typically accessed by menu picks on the main VEE window must be set using a different mechanism for VEE Pro RunTime. Two important configuration areas can be accessed by command-line options. These same features are also available as icons in the Agilent VEE Pro 8.0 RunTime Config Start menu group.

To modify the instrument configuration, run the following command:

veerun.exe -ioconfig

This runs VEE Pro RunTime and opens the Instrument Manager to allow the user to change and save the I/O configuration. This is important when the program does not have an embedded I/O configuration.

To modify the Default Preferences, run the following command:

veerun.exe -prefconfig

This runs VEE Pro RunTime and opens the Default Preferences dialog to allow the user to change and save the default preferences. Some settings that may be important to the RunTime user include:

Web Server configuration

Execution Mode (primarily for Remote Functions)

Check Instrument Addresses at PreRun

Delete Variables at PreRun

Printing configuration

Colors and Fonts (if they were not saved with the program)

Note

On systems that have both VEE Pro and VEE Pro RunTime, the two versions may or may not share the same I/O configuration settings. If the current user has a VEE Environment Variable ( such as VEEHOME85, VEEHOME90) set, both VEE versions will look for I/O configuration file in the directory defined by the VEE Environment Variable. If the current user has no VEE Environment Variable set, then VEE Pro and VEE Pro RunTime store their I/O configuration files in a per-version, per-user directory. In this case, the I/O configuration of each version must be set separately.

For configuration settings other than I/O configuration, VEE Pro and VEE Pro RunTime do not share the same configuration files. VEE Pro and VEE Pro RunTime store their own configuration files in a per-version, per-user directory. In this case, the configuration of each version must be set separately.

If the Instrument Manager or Default Preferences dialog does not fit within the VEE window, you can make the VEE or VEERun window larger by also using the -geometry option. See To Start Agilent VEE with Command Line Options for more information.

See Also

Configuring VEE for Windows, I/O Configuration Techniques.


About Agilent VEE Express

About Agilent VEE Express 8.5

Agilent VEE Express 8.5 is a subset of VEE Pro 8.5.

The following table shows the differences between Agilent VEE Pro 8.5 and Agilent VEE Express 8.5.

Features |  | Agilent VEE Pro 8.5 | Agilent VEE Express 8.5
Interfaces | GPIB, LAN, RS-232,VXI, PXI, SCXI | Support | Not support
 | USB | Support | Support (Agilent USB devices in LiveMode only)
MatlabScript Objects and MatlabScript engine |  | Support | Not support
Creating RunTime version of Agilent VEE programs and Secured version of Agilent VEE objects |  | Support | Not support
Programmatic changing of instrument addresses |  | Support | Not support
The Callable Server feature, i.e. calling Agilent VEE as an ActiveX automation server |  | Support | Not support
The Remote Function feature, i.e. importing a UserFunction that runs in another Agilent VEE process on a remote host computer |  | Support | Not support
Other features |  | Support | Support

Note

Agilent VEE Express 8.5 supports Agilent USB instruments only. If you need to support other instruments, please purchase or upgrade to Agilent VEE Pro. Note that instrument properties, e.g., the instrument address, can not be changed programmatically.

Agilent VEE Express 8.5 does not support MatlabScript objects. You cannot add new MatlabScript objects to a program or run a program with MatlabScript objects in it, but you can open a program with MatlabScript objects in it.

Agilent VEE programs, UserObjects and UserFunctions can not be saved as runtime/secured versions in VEE Express 8.5, but you still can open a RunTime version of a VEE program or import a secured UserObject or UserFunction into a VEE program.

If you need additional supports that Agilent VEE Express does not provide, please purchase or upgrade to Agilent VEE Pro.


About Agilent VEE Student

About Agilent VEE Student 8.5

Agilent VEE Student has the same features as Agilent VEE Pro 8.5 with the following limitations:

Features | Agilent VEE Pro 8.5 | Agilent VEE Student 8.5
MATLAB Script | Support | Not included*
Creating RunTime version of Agilent VEE programs and Secured version of Agilent VEE objects | Support | Not support
The Callable Server feature, i.e. calling Agilent VEE as an ActiveX automation server | Support | Not support
The Remote Function feature, i.e. importing a UserFunction that runs in another Agilent VEE process on a remote host computer | Support | Not support
Other features | Support | Support

* Although Agilent VEE Student 8.5 does not include MATLAB Script, users still can use the functionality of MATLAB in VEE as long as they have MATLAB installed on their machine. In this case, Agilent VEE Student 8.5 will use the installed MATLAB engine to process MATLAB scripts.

FAQ

1. Can I load Agilent VEE Pro programs into Agilent VEE Student?

Yes, you can load any programs developed in Agilent VEE Pro into Agilent VEE Student. Actually, Agilent VEE Student has all features that Agilent VEE Pro has except some limitations in the above table.

For programs containing MATLAB Script objects, you can load and view them, but you cannot run it unless MATLAB is installed.

2. Can I use MATLAB functionality in Agilent VEE Student?

Yes, you can use the full power of MATLAB as long as you have MATLAB installed on your PC. With MATLAB installed, you can use all MATLAB features in VEE application, such as data analysis,visualization and modeling, creating user-defined functions (M-files), and access to the MATLAB command window, the MATLAB Editor/Debugger, etc.

See Also

Welcome to Agilent VEE Pro, MATLAB Script Overview, MATLAB FAQ


VDC Array Format

Many VEE Data Containers package data in an array. Inside VEE, objects like Build Coordinate isolate you from the internal structure of these arrays. Outside VEE (in a Visual Basic client, for example), you must declare and populate these arrays correctly to avoid errors or confusion.

Consider the example of a VEE 1D array of 3D Coordinates. Immediately, you see one source of confusion: the term "dimension" is used to describe two different concepts. For coordinates, a dimension is an axes (typically referred to as "X", "Y", and "Z"). For arrays, a dimension is organization index (typically referred to as "row" and "column"). In VEE, this data type is one row of storage locations, and each storage location holds one Coordinate. Assuming a variable named "MyVeeData", the first Coordinate is MyVeeData[0], the tenth Coordinate is MyVeeData[9], etc.

Because Visual Basic does not have a "3D Coordinate" data type, a single storage location cannot hold an entire Coordinate. Packaging all the data from the "MyVeeData" array requires a 2-dimension array in Visual Basic. The rows of this array represent the coordinates; the columns of this array represent the three "X,Y,Z" values of each coordinate.

Assuming a variable named "MyVbData", the Z component of the first coordinate is MyVbData(0,2), the X component of the tenth coordinate is MyVbData(9,0), etc.

A similar arrangement is used for other VEE data types. When building a VB array for VEE Complex data, MyVbData(Element, 0) is the real component and MyVbData(Element, 1) is the imaginary component. Following is a summary of the applicable VEE data types and their array format:

VDC Data Type Array Format

Complex 1D Array Rows are complex numbers.
Column 0 is real component.
Column 1 is imaginary component.

Polar Complex 1D Array Rows are polar complex numbers.
Column 0 is magnitude component.
Column 1 is phase component.

2D Coordinate 1D Array Rows are coordinates.
Column 0 is X component.
Column 1 is Y component.

3D Coordinate 1D Array Rows are coordinates.
Column 0 is X component.
Column 1 is Y component.
Column 2 is Z component.

Coordinate 1D Array Rows are coordinates.
Column 0 is X component.
Column 1 is Y component.
Column N is Nth-dimension component.


.topic 52
Click the NI button to create an NI object for the instrument currently selected.
This could be an NI-DMM, NI-SWITCH, NI-FGEN, NI-DAQ, or NI-SCOPE.

.topic 55
Launches a new VEE with the sample file loaded. Since the correct instrument address
is already configured for the instrument you selected, all you have to do is press
Run.

.topic 53
Click the IVI-COM button to  create an IVI-COM object for the instrument currently selected. (If there is no IVI-COM driver for the instrument, this button remains grayed out.)

.topic 400
When the Profiler is started, it provides comparative information about the execution time of each UserObject and UserFunction. Clicking on any column label (such as Name, or Time) displays the Profiler data sorted on that field. Clicking again reverses the sort. Double-click on any UserObject or UserFunction shown in the Name field, and its view opens in the VEE workspace.

.topic 420
When this box is checked, data is written to the data file with commas as delimiters (separators) between the various Profiler data fields. Using comma delimiters makes it easier to import the data into some other applications, such as spreadsheets.  When this box is not checked, the data fields are aligned using multiple spaces.

.topic 1064
Specifies the local directory that will be accessible to the remote Web browser. VEE uses the file index.html in the Root Directory as its home page. A default homepage is installed as ~installDir/www/index.html. This file can be modified and/or copied to a different Root Directory.

.topic 1072
When OK is pressed, any changes to Default Preferences become valid for the current work session only. When you exit and restart VEE, the previous Default Preferences(saved in the "veerc" file) are restored.

.topic 1044
The Fonts property allows you to choose the default font for any screen element in your VEE program.

.topic 258
The Program Explorer button shows or hides the Program Explorer window. The Program Explorer shows the hierarchical structure of the current VEE program.

.topic 256
The Delete Line button provides the Delete Line cursor, which you then click on the line to be deleted. (A handy shortcut to delete lines is Ctrl-Shift-Click.)

.topic 230
The Call Stack button aids debugging by displaying the hierarchy of UserObjects or UserFunctions invoked to reach the current paused UserObject or UserFunction. Clicking on any entry in the Call Stack dialog opens that UserObject or UserFunction in the VEE workspace.

.topic 30
Click the (Interface) Properties button to view specific details about the currently selected interface. Note that VEE cannot modify the hardware characteristics of an interface or alter the configuration performed by the operating system or the I/O Config utility. If you enter different values in any of the Interface Properties fields, you must use values that match an existing, configured interface.

.topic 42
Click the Save button to save the instrument configuration to disk and close the Instrument Manager. This overwrites the vee.io file with the current configuration.  If the instrument configuration is embedded in the program, a Save from the InstrumentManager is not necessary, because an embedded configuration is saved when the programis saved.

.topic 406
The Clear button resets all Profiler data values to 0 (zero).

.topic 1046
The Number tab allows you to choose the default format for displaying numbers in your VEE program.

.topic 220
The Stop button stops execution of all program threads and closes any open files.  When a program is in the stopped state, pressing Step or Run/Resume restarts program execution from the beginning.

.topic 224
The Step Over button aids debugging by executing one primitive object at a time.  When a UserObject or UserFunction is encountered, it is executed in its entirety and is not opened into a detail view.

.topic 216
The Run button starts execution of all threads in a program. If your program has several threads, and you want to run only one of them, use a Start object to that thread instead of the Run button.

.topic 244
The Instrument Manager button provides the Instrument Manager dialog. This dialog provides convenient editing, viewing, and creating of I/O resources such as instrument transactions and drivers.

.topic 254
The Add To Panel button places the selected objects onto the panel view of the program.  If a panel view does not already exist, one is created. Panels are associated with the current context and can be nested.

.topic 22
Click the Add button to add an instrument to your I/O configuration. A manual Add operation is needed for instruments that are not discovered by the Find Instruments button. For example, RS-232 instruments or instruments connected via a LAN gateway.(An interface entry is automatically added when you add an instrument associated with that interface.)

.topic 196
The bottom line of the VEE window is a status message area. This status line shows various types of information, depending upon the current operation. For example, the program run state, error messages, pixel position of moved objects, and helpful hints.

.topic 1068
Specifies the maximum time (in seconds) that the Web server will wait for VEE to respond.

.topic 1062
When Enable Server is checked, VEE's built-in Web server is activated. The Web server allows you to monitor a VEE program from a remote Web browser.

.topic 226
The Step Out button aids debugging by executing one primitive object at a time. If the execution is in a UserObject or UserFunction, VEE completes execution of all objects in that UserObject or UserFunction.

.topic 218
The Pause button stops execution of all program threads temporarily. When a program is in the paused state, either Step or Run/Resume can be used to proceed with program execution from the point it was paused.

.topic 434
This field indicates the scope of the search. The default is the Entire Program.  If you want to limit the scope of a search, open the Find dialog from the ProgramExplorer by clicking with the right mouse button on a particular context, such as a UserFunction or UserObject.

.topic 408
The Save button writes the Profiler data to the file name specified using the Options button.

.topic 1036
When instrument checking is enabled, VEE checks the configured instruments during prerun to verify that they are accessible. If an address does not respond, you are iven the opportunity to power-on the instrument, choose a different bus address, etc. When this box is not checked, disconnected or improperly configured instruments will probably cause a timeout error when the program is running.

.topic 232
The Show Execution Flow button aids debugging by highlighting the currently executing object(s) while the program is running. In the paused or error state, Show Execution Flow highlights all objects that have already executed.

.topic 250
The Copy button places a copy of the selected objects in the Paste buffer and on the Windows Clipboard.

.topic 440
When this box is checked (the default), the search traverses all levels of nested User Objects. If not checked, only the current level is searched.

.topic 470
Creates a Formula object to Set the value of the currently selected member (property).Place the Formula in a program context. It is simply a template which can be edited as desired.

.topic 34
Click the Plug&play Driver button to create a VXIplug&play driver object for the instrument currently selected. (A VXIplug&play driver is an industry standard API based upon VISA.)

.topic 46
The Settings dialog controls some of the actions performed during instrument discovery.  If Detect only is selected, the Find Instruments button simply detects whether a device is present at each bus address. If Detect, identify, and configure... is selected, the Find Instruments button also performs an identification and driver configuration for each instrument detected. If Ask before sending... is checked, a confirmation dialog is presented before *IDN? is sent to identify each instrument. If not checked, *IDN? is sent to all instruments without operator confirmation. You may want the confirmation dialog if your system contains old, non-IEEE-488.2 instruments.

.topic 414
When this box is checked, Profiler data is shown only for those UserObjects and UserFunctions that executed.

.topic 1070
Specifies the file path to the http.log file. This file records all incoming requests processed by the Web server and can grow without bounds.

.topic 1040
When Binary RunTime File Format is checked, .vxe files are saved using a binary formatwhich gives improved security and smaller file size. When this box is not checked, .vxe files are stored in ASCII format (similar to .vee files).

.topic 444
When this box is checked, the Find text must match the entire field of the text being searched.

.topic 448
When this box is checked, a match is reported if the Find text occurs at the end of the text being searched.

.topic 1038
Specifies the number of pixels placed between objects when you perform an Edit  Align... operation. This Alignment Spacing value is used only when Space Equally is enabled.

.topic 206
The New button clears the VEE workspace. You will be prompted if there are any unsaved changes in the current program.

.topic 242
The Default Preferences button provides the Default Preferences dialog. This dialog has six tabs containing many and varied customizable VEE settings.

.topic 452
The Property buttons can be used to constrain the search according to various object properties. Once a Property is selected, specify the desired constraint in the Value column. For example, if you select Breakpoint/On, then only objects with active break points are searched.

.topic 412
This field specifies the number of digits displayed to the right of the decimal point.

.topic 1028
The Trig Mode selection chooses the default trigonometric units used in the program.  Radians are VEE's default (and fastest) units.

.topic 1076
When Reset is pressed, any pending changes to Default Preferences are discarded, and the previous Default Preferences (saved in the "veerc" file) are restored.

.topic 1052
Specifies the magnification used when printing a VEE program. Smaller numbers create a smaller image. The value you specify might be rounded by some printer drivers.

.topic 228
The Toggle Breakpoint button aids debugging by setting or clearing execution breakpoints at the selected objects. A breakpoint on an object pauses program execution immediately before that object. Breakpoints can also be accessed in the Object Menu Properties.

.topic 402
The Start Profiling button is a toggle function that starts or stops profiling.

.topic 404
Profile data is collected whenever the Profiler is running, but the data displayed in the dialog box is not updated automatically. You must click the Refresh button to cause the Profiler to display the latest profile data.

.topic 222
The Step Into button aids debugging by executing one primitive object at a time.  When a UserObject or local or imported UserFunction is encountered, VEE puts it into its detail view and executes each object in that view.

.topic 214
This area displays the run state of the program. Indicators are: Blank, Ready (stopped), Green Arrow Running, Yellow Bars Paused, Red Bars Error

.topic 246
The Function & Object Browser button provides the Function & Object Browser dialog.  This browser provides convenient access to various math operations, objects, and properties.

.topic 466
Creates a Formula object for the currently selected function or operator.  Place the Formula in a program context. It is simply a template which can be edited as desired.

.topic 202
This field indicates if the currently loaded program has any unsaved changes (modifications).When the box is "grayed out," no unsaved changes are pending.

.topic 198
This field shows the Execution Mode of the currently loaded VEE program. ExecutionMode allows newer versions of VEE to run older VEE programs with complete backwards compatibility. The possible modes are VEE 3, VEE 4, etc. up through the current VEE version. Execution Mode is saved with the VEE program and can be changed in the Default Preferences dialog.

.topic 416
This field specifies the file name where Profiler data is saved. Click this field to bring up the Save data filename dialog box.

.topic 1042
The Appearance Property Group allows you to choose the default color for any screen element in your VEE program.

.topic 450
The Object Type property constrains the search to objects of the type(s) selected in the Value list. The default is all object types. To constrain the search, click the Value button and check or uncheck the desired types. Select All and Clear All buttons are provided for convenience.

.topic 468
Creates a Formula object to Get the value of the currently selected member (property).Place the Formula in a program context. It is simply a template which can be edited as desired.

.topic 38
Click the Component Driver button to create a Component Driver object for the currently selected instrument. (A Component Driver is an efficient link to one component of an instrument's Panel Driver.)

.topic 28
Click the (Instrument) Properties button to view or modify the I/O-related properties of the currently selected instrument. The interface type determines the set of properties available. For example, RS-232 instruments have a Properties field for setting the Baud rate, while GPIB instruments have a Properties field for setting the bus address.

.topic 48
If Detect only is selected, the Find Instruments button simply detects whether a device is present at each bus address. If Detect, identify, and configure... is selected, the Find Instruments button also performs an identification and driver configuration for each instrument detected.

.topic 410
The Options button brings up the Profiler Options dialog box. These options customize the format of displayed and saved data.

.topic 384
When this box is checked, the printout includes an open view of all nested UserObjects.

.topic 1058
When Print Cover Page is checked, a cover section is generated at the beginning of the printout. This default format choice can be overridden in the Print Program dialog.

.topic 208
The Open button loads a program file into the VEE workspace, replacing any existing program. You will be prompted if there are any unsaved changes in the current program.

.topic 248
The Cut button deletes the selected objects and places them in the Paste buffer and on the Windows Clipboard.

.topic 238
The Find button provides a dialog box used to search for text strings and certain object properties in your VEE program. Various search properties, such as Match Case and Object Type, can be used to constrain your searches. To limit the scope of a search, open Find from the Program Explorer by clicking a specific context with the right-hand mouse button.

.topic 18
The Configure Drivers button identifies the selected instrument and configures any available VXIplug&play and Panel Drivers for that instrument. (Only IEEE 488.2 (and most VXI) instruments can be identified.)

.topic 32
Click the Direct I/O button to create a Direct I/O object for the instrument currently selected. (A Direct I/O object allows low-level transactions with the instrument.)

.topic 40
Click the OK button to save the instrument configuration in an internal cache and close the Instrument Manager. The current configuration is used by the program, but is not yet saved to disk.

.topic 1034
When Disable Debug is checked, all debugging features are disabled, giving the fastest program execution speed.

.topic 1024
When Auto Line Routing is checked, the lines between objects are automatically rerouted when an object is connected, moved, or resized. Auto-routing uses only horizontal and vertical lines, and gives the same results as Edit -> Clean Up Lines. When auto-routing is off, lines are drawn directly from pin to pin, often diagonally.

.topic 260
The Profiler button provides the Profiler dialog. The Profiler provides comparative information about the execution time of each UserObject and UserFunction.

.topic 212
The Print Screen button sends the visible contents of the VEE window to a printer.  To configure the printer, use File -> Print Screen.

.topic 16
When the root node is selected, click the Find Instruments button to search for available interfaces and instruments. When a specific interface is selected, click this button to search for all instruments connected to the selected interface. The exact operations performed by the Find Instruments button are controlled by the Settings dialog.

.topic 44
The Print button brings up a standard Windows Print dialog. The Instrument Manager printout is a bitmap dump of the full Instrument List tree view.

.topic 200
This field indicates if Profiling is currently enabled. When the box is "grayed out, "profiling is stopped.

.topic 388
When this box is checked, each printout page is given a page number and other header information, and an Index is generated at the end of the printout.

.topic 1032
Sets the speed at which the Data Flow markers move. Select a rate from 1 to 10. The default is 6 and the fastest is 10.

.topic 1
Save colors and fonts with program saves all the default colors and fonts in the program file that are selected in the Default Preferences dialog box. This ensures that whoever opens your program will also get all of your default colors and fonts.  If this option is not selected, only the colors and fonts explicitly set in your program are saved in your program file. This allows others using your program to retain their own default colors and fonts. If an existing program is loaded, the option is set according to how the program was saved previously.

.topic 204
This field indicates if the VEE Web Server is currently enabled. When the box is "grayed out," the Web Server is disabled. The VEE Web Server is controlled in the Default Preferences dialog.

.topic 1066
Specifies the port number used by VEE's Web server. This port number must be allocated in your system's services file and must not be used by any other Web server.

.topic 1026
When Delete Variables at PreRun is checked, the values stored in all variables are deleted before each program runs. Therefore, Get Variable objects will error if their values have not been properly set. When this box is not checked, Get Variable objects can access old data left from the previous program run. Such old data may or may not be valid for the new program run.

.topic 2
Save I/O configuration with program saves the veeio I/O configuration information with the program file, and not in the veeio resource file. The configuration information is specified in the Instrument Manager. If this option is not selected, the current program's configuration information is saved in the veeio file. If an existing program is loaded, the option is set according to how the program was saved previously.

.topic 236
The View Variables button displays a list of all variables that are currently defined.  Double-click a variable's name to view details such as type, shape, and data values.

.topic 436
When this box is checked, the search is constrained to exact matches of the letter-case specified in the Find line. The default is off, which treats upper-case and lower-case letters as equal.

.topic 26
Click the Remove button to delete an instrument entry from the I/O configuration.(An interface entry is automatically removed when all the instruments associated with that interface are removed.)

.topic 442
When this box is checked, a match is reported if the Find text occurs anywhere in the text being searched.

.topic 438
When this box is checked, all matches are reported for each object. The default is off, which reports only the first match found for each object.

.topic 472
Creates a Call object for the currently selected function. Place the Call in a program context. It is simply a template which can be edited as desired.

.topic 418
When this box is checked, each click of the Save button overwrites the data previously saved in the Profiler data file. When this box is not checked, each Save appends to the existing data.

.topic 386
When this box is checked, the printout includes a detailed view of each object in the program. All but the simplest objects are printed in open view form.

.topic 1074
When Save is pressed, any changes to Default Preferences become valid for the curren work session and are saved in the "veerc" file. When you exit and restart VEE, the new saved Default Preferences are used. (The exact path to the "veerc" file is system dependent.)

.topic 1054
When Print Header and Index Page is checked, each printout page is given a page number and other header information, and an Index is generated at the end of the printout.  This default format choice can be overridden in the Print Program dialog.

.topic 1056
When Print Program Explorer is checked, the printout includes the overview information contained in the Program Explorer window. This default format choice can be overridden in the Print Program dialog.

.topic 240
The Find Results button displays the results from the most recent Find search. You can change the sorting order of a column by clicking on the column header.

.topic 432
Enter the text string you want to find in your VEE program. If you leave this line blank, the search will match any text.

.topic 446
When this box is checked, a match is reported if the Find text occurs at the beginning of the text being searched.

.topic 24
Click the Remove button to delete an instrument entry from the I/O configuration.(An interface entry is automatically removed when all the instruments associated with that interface are removed.)

.topic 392
When this box is checked, the printout includes the overview information contained in the Program Explorer window.

.topic 390
When this box is checked, a cover section is generated at the beginning of the printout.

.topic 1060
When Print I/O Configuration is checked, the printout includes the expanded treeview of the I/O configuration (from the Instrument Manager). This default format choice can be overridden in the Print Program dialog.

.topic 1050
The B&W Printer Darkness setting allows you to choose a shade of gray for each screen element in your VEE program. This shade of gray is used when you print the program on a non-color printer. (The settings in the Appearance Property Group are used for a color printer.)

.topic 234
The Show Data Flow button aids debugging by visually indicating the route that data takes through the program. The speed of the small square data marker is set in the Default Preferences   General tab, Debug area.

.topic 210
The Save button writes the current program to the previously specified file name.  Save uses the file shown in the VEE window title bar. If this is a New program that has not been saved previously, you will be prompted for a file name. To change filenames, use File -> Save As.

.topic 394
When this box is checked, the printout includes the expanded tree view of the I/O configuration (from the Instrument Manager).

.topic 50
If Ask before sending... is checked, a confirmation dialog is presented before *IDN? is sent to identify each instrument. If not checked, *IDN? is sent to all instruments without operator confirmation. You may want the confirmation dialog if your system contains old, non-IEEE-488.2 instruments.

.topic 252
The Paste button places a copy of the Paste buffer onto the VEE workspace. You can Paste objects that were accidentally Cut, and connections to those objects will be restored.

.topic 454
The Reset button restores the default Property/Value list, which is all object typeswith no constraints.

.topic 464
This browser presents functions and objects in a hierarchical arrangement. Choose the broad classification from the left column, the sub-category from the middle column, and the specific function or object from the right column. Then click one of the Create... buttons (or double-click the selection) to create a VEE object from your selection. Place this VEE object in a program context and edit it as desired.

.topic 474
Displays Help for the currently selected function or object (not Help about the Browser).

.topic 36
Click the Panel Driver button to create a VEE Panel Driver object for the currently selected instrument. (A Panel Driver is the full-featured graphical simulation of an instrument's front panel.)


.NET and COM

Using .NET objects and COM objects inter-operatively means you have to reconcile how the two exist in memory. .NET objects exist in managed memory, which is controlled by the CLR, and they can be moved during runtime as needed to improve performance. COM objects reside in unmanaged memory and their pointers are to locations in memory that do not move.

Since the two manage memory very differently, a wrapper is needed to help them communicate. The diagram below shows how .NET makes use of wrappers to make the communication between the two transparent. These two wrappers are the foundation of the .NET Framework's COM interop strategy. For in-depth and understandable reviews of the Runtime Callable Wrapper and the COM Callable Wrapper, see the articles in MSDN by Mike Gunderloy. They are entitled “Calling COM Components from .NET Clients” and “Calling a .NET Component from a COM Component”.


Error 756

Error 756 is generated when VEE fails to create a .NET object with the CreateInstance built-in function. The following check list might help you debug and fix the error.

Error 756 Checklist

  1. Did you add a reference to the assembly that the .NET class is in?

  2. Open the Function & Object Browser, select the assembly, the namespace and the class type you want, if you do not see the class that you want, then you cannot create a .NET object of that class type.

  3. Do you see any constructors for that class? If there is no constructors for that class, you are not able to create a .NET object of that class type.

  4. Is the .NET object a declared or undeclared variable? If it is, try to check the "Delete Variable at PreRun" under General tab in the Default Preference dialog box, or put an "Delete Variable" at the begin of your program to delete the variable. For further information, refer to example program at Autodispose.vee.

  5. Did you use the Create Instance button to create the formula template? If you did, you should be able to avoid a lot of common mistakes such as mistyping the assembly name or class name.

  6. Unlike CreateObject in COM, constructors of .NET classes may take any number of parameters. So make sure you provide the correct number of parameters with correct types to the CreateInstance call. If you use the Function & Object Browser, VEE helps you select the right constructor and provides placeholders for the correct number of input parameters. You must make sure the parameter types are correct as well.

  7. Read the VEE error box. .NET exceptions typically provide a lot more content than COM. If the content does not help, check MSDN if the class is from the .NET common class library.


Error 300
The input terminal number <n> is not connected

Resolution

You may get this error message in three different situations:

1. When a data input pin is not connected.

All data input terminals on an object must be connected before a program can run. Find the object that caused the error (the object with a red outline) and make the necessary connections.

2. On a UserObject/UserFunction when an inside pin of an output terminal is not connected.

You may get this message on a UserObject or UserFunction when the error message mentions the input terminal of an output buffer. This means the inside pin of an output terminal is not connected to an object inside the UserObject or UserFunction. All inside pins of output terminals must be connected before a program can run.

To determine which pin is not connected, look at the open view of the UserObject or the editing view of the UserFunction. From the Properties Window, select Show Terminals to view the terminal area.

3. When importing a UserFunction.

If you've gotten this message when importing a UserFunction, there is an object inside the UserFunction that has an unconnected input terminal. You need to load the UserFunction via File [image] Open File [image] Merge Library, modify the UserFunction, and save it. Open the previous program and run it; the UserFunction will import properly.


Error 553
An ActiveX object returned an error during <action> <name>.

Resolution

This error happens when an ActiveX object returns the error code DISP_E_EXCEPTION. This error can be caused by passing bad values to a property or method. It can also be caused when an ActiveX object is requested to "error" in certain situations. For instance, the Windows Common Dialog control provides access to several common dialog boxes. You can set these dialog boxes to "error" if the user presses the Cancel button. In this case, the ActiveX object returns an error indicating that the Cancel button was pressed.


Error 557
ActiveX object could not be created.

Resolution

There are various reasons why VEE may not be able to create an ActiveX object. A resolution to the problem depends on the reported error code:

If the error code reported by VEE is 0x80080005, then Windows was unable to load the ActiveX server or control based on the information in the registry. This error can occur when the server or control is registered in a directory with a long file name that contains a space and a similar directory name exists at the same level. For more information see Microsoft Knowledge Base Article Q179690. The recommended solution is to install the server or control in a directory without spaces in the path or in a directory that isn't named similar to other directories at the same level.

If the ActiveX object indicates an error code of 0x80040112, then the control is licensed. This error can appear if the licensed control is not installed properly. When the full control package is installed properly, a license exists that lets you create an instance of the control when developing a VEE program. VEE requests a license key from the control and saves this key with your VEE program. This method lets you distribute a copy of the control’s file with your program to one or more target computers. VEE presents this key to the control on a target computer, allowing VEE to create an instance of the control.

This error message can appear if you try to use the control on target computers. You cannot use the control to create new programs, and you cannot clone or copy/paste the control in an existing program. Remember, the control is not licensed on the target computer for you to use; the license key only allows VEE to reference the control. You must purchase and install the full control package.


Error 593
MATLAB Script execution error

Resolution

Numerous MATLAB run-time errors are all mapped to VEE Error 593, and the "Go To" button on the VEE error box shows only the MATLAB Script Object, not individual MATLAB program lines. This means you must do some troubleshooting to find and correct the actual problem which caused error 593. Two helpful hints are: Read the MATLAB error message text, and use the msgbox function. These are demonstrated in the following example.

This small VEE example reads a vector of "Y" values from a file, generates a linear ramp of "X" values, and plots an X-Y graph using those two vectors. Assume that the following error occurs when this program is run.

Note the second paragraph in this dialog box contains the error message generated by MATLAB Script, in this case, Invalid fid. This means the fscanf function was given an invalid file identifier. To investigate further, display the value returned by the fopen function. For example, insert a line as shown below:

dfile=fopen('C:sineWave.txt','r')
uiwait(msgbox(int2str(dfile)))
ydat=fscanf(dfile,'%f')

The second line shows some useful debugging techniques for MATLAB Script. The combination uiwait(msgbox(...)) displays a text box and waits for you to press its OK button. Since there are no "line probes" or "watch windows" to view MATLAB variables, message boxes are a convenient way to display values while debugging. The msgbox function requires a string parameter, so the int2str function is used to convert the numeric file ID.

When the example is run with the added debug line, the message box reports a file ID of -1. The MATLAB Help Desk topic for fopen says that -1 is the value returned when an fopen fails. In other words, the fscanf function saw an invalid file ID because no file was opened. This could happen for any of the typical file-system reasons, such as no permissions, misspelled path name, etc. Assume that you correct the file path and rerun the example. The following error results.

Again, the second paragraph shows the MATLAB error message. In this case, the plot function failed because the X and Y vectors are not the same length. You could use msgbox to inspect the length of xdat and ydat, or you could review the semantics of the MATLAB colon operator. Either way, you would be reminded that MATLAB arrays start with element "0". Therefore, if length(ydat) is 256, then the xdat ramp is created with 257 elements: 0..256. The corrected statement is:

xdat=0:1:length(ydat)-1;

This is just an imaginary example, but it introduces techniques which are helpful when debugging any MATLAB Script object. In summary:

Look for details in the MATLAB error message. The second paragraph in the "VEE Run Time Error" dialog lists the failed MATLAB function and a line about the nature of the problem.

Insert msgbox to display values. Convert numeric values to strings before displaying. Remember to remove any unneeded msgbox lines after they are no longer needed for debugging.

Make liberal use of the MATLAB documentation. To view MATLAB Help from the VEE Window, select: Help [image] MATLAB Script [image] Help Desk


Error 601
Invalid expression: <description>

Resolution

If this error appears with a <description> referring to a syntax error in a Formula object expression, check the following conditions:

1. Be sure each expression ends with a ";" (semi-colon). Though the message indicates the error’s location, a semi-colon may be missing from the end of the previous expression, and that expression may be on the previous line.

2. Avoid using variable names in lower execution modes that are unique keywords in a higher execution mode. This includes keywords such as Set and ByRef. To check the program’s execution mode setting, look in the status bar in the lower right corner of the VEE window.

3. Avoid assigning a value to a built-in constant. VEE defines the following built-in constants in VEE 5 (or higher) execution mode: TRUE, FALSE, PI.

4. Triadic operators require parentheses around the whole statement:

Right:
(a==0 ? TRUE : FALSE)

Wrong:
a==0 ? TRUE : FALSE

5. In an expression that builds or modifies an array, the syntax requires comma-separated indices:

Right:
[1,1,0]

Wrong:
[1 1 0]


Error 739
Stack pointer corrupted after return from compiled function <function_name>

Resolution

The most common cause of stack pointer corruption is using the wrong calling convention for a function’s prototype. This declaration is found in your definition (.h) file. If no calling convention is specified, VEE assumes the _cdecl convention by default. For example, these two declarations are the same to VEE, and both result in a _cdecl function:

long func1(long a, long b)
long _cdecl func1(long a, long b)

The most common alternative is the __stdcall convention. It can be specified explicitly or with a common macro. For example, these two declarations both declare in a __stdcall function:

long __stdcall func2(long x)
long WINAPI func2(long x)

One primary purpose of a calling convention is to determine who "cleans up" the stack. Either the caller (VEE) or the callee (your function) can perform this cleanup. It is essential that stack cleanup be performed in one, and only one place. If the function prototype does not match the function code in the DLL, the stack pointer might be repositioned twice or not at all. Either form of mismatch is potentially fatal to program execution.

Almost all Win32 API functions use the __stdcall calling convention. Only those Win32 API functions that take a variable number of arguments are _cdecl. Any DLL that works with Visual Basic, uses the __stdcall calling convention. Most DLLs written in C use the _cdecl calling convention, unless the function is declared as __stdcall, or the DLL is compiled with the /Gz Microsoft compiler option.

Another potential cause of stack pointer corruption for a __stdcall function is if the wrong number or the wrong type of parameters are declared in the function prototype.

In VEE 8.0 and later versions, using the .NET Framework 2.0 and later, this stack pointer corruption is also caught by the .NET Execution Engine. In some cases, the .NET Execution Engine will perceive this stack corruption as a security risk and will terminate the VEE process. VEE will attempt to pop-up a message box telling you that it is about to exit before it is terminated. VEE cannot recover from a stack pointer corruption.

The quickest fix for this error is to modify the definition (.h) file, making it properly describe the behavior of the DLL. VEE will read the new definition the next time you run your program. (To see the name of the definition file, check VEE’s Import Library object.)


Error 751

The most common cause of error 751 is a System.MissingMemberException or System.MissingMethodException has been thrown during a .NET operation. In this case, there are several things that might help you debug and fix the error.

Checklist for Error 751

1. Did you use the Function & Object Browser to generate the template? You should be able to avoid a lot of 751 errors by using the Function & Object Browser.

2. Check the spelling for the member you want to invoke.

3. Do you mean to invoke a method or a property? A method requires “(“ and “)” even if it has no parameters. A property typically does not have “(“ and “)” unless it is an indexed or parameterized property.

4. Did you provide the right number of parameters?

5. Does each parameter have the correct type? .NET operations in VEE will usually accept a precision-widening data type as a parameter, but not a precision narrowing data type, e.g., you may pass VEE’s UInt8 to a .NET operation that requires a parameter of type Int16, but not the other way around. Also, if the .NET operation requires a ByRef parameter and you want to retrieve its result back, then the data type has to be exactly as required, e.g., if the .NET method requires a parameter of type ByRef Int32, then you can only pass VEE’s ByRef Int32 data type. If you don’t care about retrieving the result back, then you may skip the ByRef keyword and the normal parameter rule would apply.

6. If you are calling a Static (aka Shared) member, indicated by an 'S' in the icon within the Function & Object Browser, you must not use an instance variable. Use the class name to call a Static (aka Shared) member. The Function & Object Browser automatically generates the correct syntax using the class name (even taking into account namespace imports) for you for static (AKA Shared) members.

See Also

About .NET Errors in VEE


Error 810

Instrument driver error <n>: <description>
Refer to your instrument manual for further information

Resolution

An instrument error has occurred. This error shows the instrument error that was passed from the instrument, to the instrument driver, into VEE

For example, the error may look like:
Instrument driver error 1051: Device xxx reported error nnn

"xxx" - is the name you assigned to the instrument under I/O [image] Instrument Manager.

"nnn" - is the instrument's error message to look up in your instrument manual to find what the error really is. Your instrument manual will give details.


Error 811

I/O error or timeout occurred

Resolution

This error occurs when VEE cannot communicate with the instrument. The following actions often solve this problem:

Double-check that the instrument is plugged in and turned on.

Check the cable connections, make sure they're tight.

Make sure the I/O address is correct.

When using instrument drivers, make sure you've specified the correct driver file for the instrument.

Note

If transferring a large amount of data or the instrument is slow, increase the timeout value via the I/O [image] Instrument Manager.


Error 851
There is no Service Manager on host, <name>

Resolution

The Service Manager could not be started. You may get this error message in when:

1. The Service machine does not have the Service Manager started.

For Programs Running on Windows NT:

The Service Manager is a console application named veesm.exe found in the VEE installation directory. Start it by using Run from the Start Menu:

"C:\Program Files\Agilent\VEE 5.0\veesm.exe"

If you prefer, put the Service Manager in the Startup group so that it is automatically started when Windows starts running. Set the shortcut properties to so that the Service Manager will run minimized.


Error 906
Thread with feedback requires START object

Resolution

Feedback allows you to set initial values or access values from previous iterations of a loop.

To use feedback, you must have a Start object connected to an object in the feedback loop to indicate which object (or subthread) should execute first.


Error 910
Process is out of memory, save your program IMMEDIATELY

Resolution

Save your program to a different file name immediately.

For Programs Running on Windows NT:

The program has used up all available swap space.

One possible cause is if the program allocates very large arrays or records, and performs operations on these structures in their entirety. If so, you may want to modify the program to perform operations on only parts of the structures.

Otherwise, you will need to allocate more swap space before you can run the VEE program that used all the swap space.

On Windows NT: Click the right mouse button on My Computer and select Properties. Select the Performance tab, and choose the Virtual Memory button to adjust your virtual memory settings.


Error 935
A Junction is required inside of feedback cycles.

Resolution

In VEE 4 (or higher) compatibility mode, a Junction object is required inside of a feedback cycle. Start objects are no longer required.

Refer to Help => Contents and Index => Tell me about.. => I/O Transaction.


Error 937
Sample & Hold was not given any data.

Resolution

The XEQ pin of a Sample & Hold object has been hit, but the object does not contain data. Therefore there is no data to output. Change your program to ensure data is sent to the Sample & Hold object before the XEQ pin is executed. This error is only generated in VEE 4 (or higher) compatibility mode.


Error 938
VEE was unable to compile this part of the program.

Resolution

In VEE 3.x and older versions, you could intersect iteration objects. The execution order was undefined but was affected by the order the connections were made. This is also true for programs running in VEE 3 compatibility mode.

In VEE 4.x and newer versions, when compatibility mode is set to VEE 4 (or higher), only loops that intersect via a Junction object are allowed. Any other intersecting loops generate this error.

Refer to Help => Contents and Index => Tell me about.. => I/O Transaction.


Error 939
Cannot push START when thread is connected to input terminals.

Resolution

You have a UserObject or UserFunction that contains a Start object that, when pressed, would try to run a thread that depended on data generated outside the context. Because only objects inside the context execute when Start is pressed, the missing data prevents one or more objects from executing; the missing data generates this error. This error is only generated in VEE 4 (or higher) compatibility mode.

Solutions include:

Provide data to the objects. Temporarily disconnect the inputs from the UserObject or UserFunction input terminals and connect them to Constant object or other objects that output data. Or use a Junction to provide an initial value.

Separate the section of thread you were trying to debug by putting it in a separate UserObject and running it by itself.


Error 940
Illegal form of feedback

Resolution

This error is generated in VEE 4 (or higher) compatibility mode when a feedback loop exists without an iterator. Because there is no iterator, the feedback loop is not complete.

Either insert an iterator into the program to complete the loop or take out the Junction object to eliminate the feedback.


Error 941
T1 must be activated before T2.

Resolution

In VEE 4 (or higher) compatibility mode, the top-most data input pin (T1) of a Timer object must be executed before the bottom data input pin (T2). Either switch the line connections (between T1 and T2) or change the program logic so that the pins are executed in the correct order.


Error 950 through 999

These error codes are used by Agilent VEE internal operations, and should not appear in normal operation. If one of these error codes appears, you will see the following box:

Before submitting an error report, be sure to check for updates. Agilent occasionally issues patch files that may provide a fix for the problem you are experiencing. The Internal Error type, error number, Object title, and Object type will vary. Please enter your name, email address, and then press the Send Error Report button. A mini-dump will be sent to Agilent. Mini dumps help Agilent track reliability issues and quickly identify and correct these problems. In some cases, Agilent may need your help to reproduce the defect, in these cases you will be contacted using the email address you provide. If you do not want to be contacted, please leave these fields blank. In any case, please send the error report. Even without the ability to reproduce an error, these reports provide valuable information about the product. Please review the additional information regarding mini-dumps at the end of this topic.

Caution

Before you proceed, you should be aware that VEE will not let you save over the existing program file when you encounter this type of error. However, you can save the broken program with a different name. It may load and run for several days without problems, and later execute a corrupt part of the program, repeating this or a similar error.

The original program saved on the hard disk is not affected by this error. Follow these steps to decide how to proceed with your programming:

1. Save the program to a new file name, and exit VEE.

2. Check if the new program is corrupt, by opening and running it in a new VEE window, making sure to exercise all of its threads. Choose one of the following options, depending on the results:

a. If the new program opens and runs without errors, you can continue using it. Be aware that a corrupted area may still exist. If the program continues to perform reliably, then it probably is not corrupt.

b. If the new program opens and runs without errors, you can choose not to use it to avoid potential problems. You can still refer to it for programming changes not saved in the original program. You should not copy threads from the new program to the original, since the copy may contain corrupted areas. Keep the new program for reference when explaining the problem to Agilent Support.

c. If the new program is corrupt, please do not delete it. Keep the new program for reference when explaining the problem to Agilent Support. Certain program artifacts may exist that will be useful. Exit VEE without saving the program, then open the original program in a new VEE window to continue programming.

Mini-Dumps

VEE uses mini-dumps to save enough information to recreate most of the details concerning the process that is currently running. This information includes the values of parameters to each function, local variable values in each of these functions as well as memory associated with local variables that are pointers, and more. This information allows Agilent to more easily determine the cause of the error.

Mini-dumps also include the full path to all the executable modules including the VEE executable and any DLLs that may also be loaded including any that have been imported into VEE via the Import Library object. Note also that if there is sensitive information in your VEE program such as passwords, code names, etc., that information could be found in the mini-dump that is sent back to Agilent. Agilent will take reasonable precautions to protect the privacy of the information contained in these error reports. However, you are under no obligation to send these error reports to Agilent.


File Open Dialog Box

A Windows standard File Open dialog box that appears when you click MyFile button in the Import Library object, the To/From File object, or the To/From Dataset object.

Select the file you want to import in this dialog box, then click the Open button to close this dialog box. The name and the path of the selected file will replace the text "MyFile" on the button in the corresponding object.

When you save your VEE program, the name and path of the file selected will be saved in your VEE program too. Uncheck the Save as Relative Path at the bottom of the dialog box, if you want to save the absolute path of the file; Check the Save as Relative Path, if you want to save the relative path to the current directory with your VEE program.

Current directory is the directory the Agilent VEE is launched from. Moving the mouse cursor over the button next to the To File in the To/From File object, To/From DataSet object, or Import Library object brings up a tooltip showing the current directory. For example, in the following figure, the current directory is c:\VEE.


What has been Fixed in This Release

What has been Fixed in Version 8.5

ID | Descriptions
28818 | VEE can't load programs including UF name that starts with Full size Japanese characters.
28803 | VEE Hangs when programmatically changing the field value in a record when the field type is Enum, Record or COM Object.
28825 | VSE: Changing Legacy interface to Visa interface will cause VSE.
29139 | VSE when double clicking items in Find Result window if these items are from a remote UserFunction.
28899 | Pops up "timeout" caution message after second execution for all VISA instruments.
28806 | Watch window: double byte characters (Chinese/Japanese) only appear half in Watch window.
28857 | Unhandled exception when change the InitialValue of an Int64 constant in Properties window.
29502 | Vee uses the wrong number of points to calculate a sample interval when displaying a waveform.
28821 | VSE: Executing I/O Transaction with I/O Monitor enabled will cause VSE.
28886 | Dynamic menu items: Assertion failed when launch .net operation builder during running state.
29197 | Exception occurs when removing DeclaredName from a Textbox object.
27998 | Clicking on the Call user function object in one lib jumps to the wrong lib.
29121 | Program Explorer: Imported UF does not updated after changing the title.
29114 | Program Explorer: Generating of variables should be disable for Secured Userfunctions.
29479 | Minimap: Minimap is not updated when opening UserFunction or User Object and no mouse movement.
28667 | VSE in MessageBox while select "X" in Custom buttons.
22845 | Scissors mouse cursor reset when over a formula box.
28880 | One minute one time delay occurs during initialization if the instrument does not support RQS event.
29059 | Property Grid: LabelSpacing can't be modified after certain steps.
28777 | Int64: elementary power result is wrong if input is array.
29519 | Error message pops up when clicking the "show config" meun of Legacy device without the Enable Legacy I/O button checked.
29568 | Wrong result when a boolean multiply a Coord.
29585 | VEE launch very slow if user can not connected to the internet because of the defect of .NET Framework 2.0 authenticode checking.
28894 | Watch window should show a rotating hourglass when expanding a 6000 long record array node since it will take a long time.
28206 | New Workbook, Create Chart, Save failed when using Excel 2007 Beta2TR.
28722 | Can't programmatically change the PopupPanelTitle of Main for VXE file.
28733 | Visible property can't work well if the device has no declared name.
28482 | Vee hangs when edit user object which has a drop down list in the panel.
29342 | Minidumps should not overrun user's disk space, rather should replace older dumps.
28734 | .Vxe and .Vee file icons are the same.
29032 | Restored UO can't restore to default backcolor if the UO has declared a variable name.
28837 | TypeName(x) gives error " Value is nil or empty (could be zero-element array)"when the input is a zero element record array.
28881 | enableEOI property is ignored for VISA.
28620 | Does not give the correct visa address sample in function & object browser.
28778 | Watch Window:unhandled exception happens when press "Ctrl+C" after open Watch window.
28873 | Pops up "GPIB-VISA interface type in Instrument configuration file not enabled" when load some programs in previous versions of VEE.
28779 | 8.0 VXE file has double size of 7.5 VXE file.
28885 | Slider: EnableEditing property set to false still can be edited after run..
28689 | VEE hangs when select 'save as.." after key in 'out of range number' for int array.
28655 | PanelDrawGrid's gone forever after added/removed a background picture.
28783 | Assersion: when using Double Byte Character Set in Watch window.
29122 | VSE: do undo with Properties window on.
28891 | EnableEditing will return to default value (true) after execution or opening.
29204 | Need a "Generate" context menu for Declare Variable object.
28658 | Context menu of Watch Window displays improperly when the window is empty.

VSE: VEE Serious Error

Copyright (c) 1991-2007 Agilent Technologies, Inc.


HC_BrowserCall

Creates a Call object for the currently selected function. Place the Call in a program context. It is simply a template which can be edited as desired.


HC_BrowserFormula

Creates a Formula object for the currently selected function or operator. Place the Formula in a program context. It is simply a template which can be edited as desired.


HC_BrowserGet

Creates a Formula object to Get the value of the currently selected member (property). Place the Formula in a program context. It is simply a template which can be edited as desired.


HC_BrowserHelp

Displays Help for the currently selected function or object (not Help about the Browser).


HC_BrowserSelectArea

This browser presents functions and objects in a hierarchical arrangement. Choose the broad classification from the left column, the sub-category from the middle column, and the specific function or object from the right column. Then click one of the Create... buttons (or double-click the selection) to create a VEE object from your selection. Place this VEE object in a program context and edit it as desired.


HC_BrowserSet

Creates a Formula object to Set the value of the currently selected member (property). Place the Formula in a program context. It is simply a template which can be edited as desired.


HC_FindAllMatches

When this box is checked, all matches are reported for each object. The default is off, which reports only the first match found for each object.


HC_FindMatchCase

When this box is checked, the search is constrained to exact matches of the letter-case specified in the Find line. The default is off, which treats upper-case and lower-case letters as equal.


HC_FindNested

When this box is checked (the default), the search traverses all levels of nested UserObjects. If not checked, only the current level is searched.


HC_FindObjectType

The Object Type property constrains the search to objects of the type(s) selected in the Value list. The default is all object types. To constrain the search, click the Value button and check or uncheck the desired types. Select All and Clear All buttons are provided for convenience.


HC_FindOtherProperty

The Property buttons can be used to constrain the search according to various object properties. Once a Property is selected, specify the desired constraint in the Value column. For example, if you select Breakpoint/On, then only objects with active breakpoints are searched.


HC_FindReset

The Reset button restores the default Property/Value list, which is all object types with no constraints.


HC_FindSearchIn

This field indicates the scope of the search. The default is the Entire Program. If you want to limit the scope of a search, open the Find dialog from the Program Explorer by clicking with the right mouse button on a particular context, such as a UserFunction or UserObject.


HC_FindShowBegin

When this box is checked, a match is reported if the Find text occurs at the beginning of the text being searched.


HC_FindShowContain

When this box is checked, a match is reported if the Find text occurs anywhere in the text being searched.


HC_FindShowEnd

When this box is checked, a match is reported if the Find text occurs at the end of the text being searched.


HC_FindShowExact

When this box is checked, the Find text must match the entire field of the text being searched.


HC_FindTarget

Enter the text string you want to find in your VEE program. If you leave this line blank, the search will match any text.


HC_IconAddToPanel

The Add To Panel button places the selected objects onto the panel view of the program. If a panel view does not already exist, one is created. Panels are associated with the current context and can be nested.


HC_IconBreakpoint

The Toggle Breakpoint button aids debugging by setting or clearing execution breakpoints at the selected objects. A breakpoint on an object pauses program execution immediately before that object. Breakpoints can also be accessed in the Object Menu Properties.


HC_IconCallStack

The Call Stack button aids debugging by displaying the hierarchy of UserObjects or UserFunctions invoked to reach the current paused UserObject or UserFunction. Clicking on any entry in the Call Stack dialog opens that UserObject or UserFunction in the VEE workspace.


HC_IconCopy

The Copy button places a copy of the selected objects in the Paste buffer and on the Windows Clipboard.


HC_IconCut

The Cut button deletes the selected objects and places them in the Paste buffer and on the Windows Clipboard.


HC_IconDefaultPrefs

The Default Preferences button provides the Default Preferences dialog. This dialog has six tabs containing many and varied customizable VEE settings.


HC_IconDelLine

The Delete Line button provides the Delete Line cursor, which you then click on the line to be deleted. (A handy shortcut to delete lines is Ctrl-Shift-Click.)


HC_IconFind

The Find button provides a dialog box used to search for text strings and certain object properties in your VEE program. Various search properties, such as Match Case and Object Type, can be used to constrain your searches. To limit the scope of a search, open Find from the Program Explorer by clicking a specific context with the right-hand mouse button.


HC_IconFindResults

The Find Results button displays the results from the most recent Find search. You can change the sorting order of a column by clicking on the column header.


HC_IconFuncBrowser

The Function & Object Browser button provides the Function & Object Browser dialog. This browser provides convenient access to various math operations, objects, and properties.


HC_IconInstrMgr

The Instrument Manager button provides the Instrument Manager dialog. This dialog provides convenient editing, viewing, and creating of I/O resources such as instrument transactions and drivers.


HC_IconNew

The New button clears the VEE workspace. You will be prompted if there are any unsaved changes in the current program.


HC_IconOpen

The Open button loads a program file into the VEE workspace, replacing any existing program. You will be prompted if there are any unsaved changes in the current program.


HC_IconPaste

The Paste button places a copy of the Paste buffer onto the VEE workspace. You can Paste objects that were accidentally Cut, and connections to those objects will be restored.


HC_IconPause

The Pause button stops execution of all program threads temporarily. When a program is in the paused state, either Step or Run/Resume can be used to proceed with program execution from the point it was paused.


HC_IconPrint

The Print Screen button sends the visible contents of the VEE window to a printer. To configure the printer, use File [image] Print Screen.


HC_IconProfiler

The Profiler button provides the Profiler dialog. The Profiler provides comparative information about the execution time of each UserObject and UserFunction.


HC_IconProgExplorer

The Program Explorer button shows or hides the Program Explorer window. The Program Explorer shows the hierarchical structure of the current VEE program.


HC_IconRun

The Run button starts execution of all threads in a program. If your program has several threads, and you want to run only one of them, use a Start object to that thread instead of the Run button.


HC_IconRunState

This area displays the run state of the program. Indicators are:

Blank Ready (stopped)
Green Arrow Running
Yellow Bars Paused
Red Bars Error


HC_IconSave

The Save button writes the current program to the previously specified file name. Save uses the file shown in the VEE window title bar. If this is a New program that has not been saved previously, you will be prompted for a file name. To change file names, use File [image] Save As.


HC_IconShowData

The Show Data Flow button aids debugging by visually indicating the route that data takes through the program. The speed of the small square data marker is set in the Default Preferences [image] General tab, Debug area.


HC_IconShowExec

The Show Execution Flow button aids debugging by highlighting the currently executing object(s) while the program is running. In the paused or error state, Show Execution Flow highlights all objects that have already executed.


HC_IconStepIn

The Step Into button aids debugging by executing one primitive object at a time. When a UserObject or local or imported UserFunction is encountered, VEE puts it into its detail view and executes each object in that view.


HC_IconStepOut

The Step Out button aids debugging by executing one primitive object at a time. If the execution is in a UserObject or UserFunction, VEE completes execution of all objects in that UserObject or UserFunction.


HC_IconStepOver

The Step Over button aids debugging by executing one primitive object at a time. When a UserObject or UserFunction is encountered, it is executed in its entirety and is not opened into a detail view.


HC_IconStop

The Stop button stops execution of all program threads and closes any open files. When a program is in the stopped state, pressing Step or Run/Resume restarts program execution from the beginning.


HC_IconViewVars

The View Variables button displays a list of all variables that are currently defined. Double-click a variable's name to view details such as type, shape, and data values.


HC_InstrMgrDlgAdd

Click the Add button to add an instrument to your I/O configuration. A manual Add operation is needed for instruments that are not discovered by the Find Instruments button. For example, RS-232 instruments or instruments connected via a LAN gateway. (An interface entry is automatically added when you add an instrument associated with that interface.)


HC_InstrMgrDlgComponent

Click the Component Driver button to create a Component Driver object for the currently selected instrument. (A Component Driver is an efficient link to one component of an instrument’s Panel Driver.)


HC_InstrMgrDlgConfigDrivers

The Configure Drivers button identifies the selected instrument and configures any available VXIplug&play and Panel Drivers for that instrument. (Only IEEE 488.2, and most VXI, instruments can be identified.)


HC_InstrMgrDlgDirectIO

Click the Direct I/O button to create a Direct I/O object for the instrument currently selected. (A Direct I/O object allows low-level transactions with the instrument.)


HC_InstrMgrDlgFindInstr

When the root node is selected, click the Find Instruments button to search for available interfaces and instruments. When a specific interface is selected, click this button to search for all instruments connected to the selected interface. The exact operations performed by the Find Instruments button are controlled by the Settings dialog.


HC_InstrMgrDlgIVICOM

Click the IVI-COM button to create an IVI-COM object for the instrument currently selected. (If there is no IVI-COM driver for the instrument, this button remains grayed out.)


HC_InstrMgrDlgLoadSampls

Launches a new VEE with the sample file loaded. Since the correct instrument address is already configured for the instrument you selected, all you have to do is press Run.


HC_InstrMgrDlgNidaq

Click the NI button to create an NI object for the instrument currently selected. This could be an NI-DMM, NI-SWITCH, NI-FGEN, NI-DAQ, NI-SCOPE, or NI-DAQmx.


HC_InstrMgrDlgOK

Click the OK button to save the instrument configuration in an internal cache and close the Instrument Manager. The current configuration is used by the program, but is not yet saved to disk.


HC_InstrMgrDlgPanel

Click the Panel Driver button to create a VEE Panel Driver object for the currently selected instrument. (A Panel Driver is the full-featured graphical simulation of an instrument’s front panel.)


HC_InstrMgrDlgPnP

Click the Plug&play Driver button to create a VXIplug&play driver object for the instrument currently selected. (A VXIplug&play driver is an industry standard API based upon VISA.)


HC_InstrMgrDlgPrint

The Print button brings up a standard Windows Print dialog. The Instrument Manager printout is a bitmap dump of the full Instrument List tree view.


HC_InstrMgrDlgPropertiesInstr

Click the (Instrument) Properties button to view or modify the I/O-related properties of the currently selected instrument. The interface type determines the set of properties available. For example, RS-232 instruments have a Properties field for setting the Baud rate, while GPIB instruments have a Properties field for setting the bus address.


HC_InstrMgrDlgPropertiesIntf

Click the (Interface) Properties button to view specific details about the currently selected interface.

Note that VEE cannot modify the hardware characteristics of an interface or alter the configuration performed by the operating system or the I/O Config utility. If you enter different values in any of the Interface Properties fields, you must use values that match an existing, configured interface.


HC_InstrMgrDlgRemoveInstr

Click the Remove button to delete an instrument entry from the I/O configuration. (An interface entry is automatically removed when all the instruments associated with that interface are removed.)


HC_InstrMgrDlgRemoveIntf

Click the Remove button to delete an instrument entry from the I/O configuration. (An interface entry is automatically removed when all the instruments associated with that interface are removed.)


HC_InstrMgrDlgSave

Click the Save button to save the instrument configuration to disk and close the Instrument Manager. This overwrites the vee.io file with the current configuration.

If the instrument configuration is embedded in the program, a Save from the Instrument Manager is not necessary, because an embedded configuration is saved when the program is saved.


HC_InstrMgrDlgSettings

The Settings dialog controls some of the actions performed during instrument discovery.

If Detect only is selected, the Find Instruments button simply detects whether a device is present at each bus address. If Detect, identify, and configure... is selected, the Find Instruments button also performs an identification and driver configuration for each instrument detected.

If Ask before sending... is checked, a confirmation dialog is presented before *IDN? is sent to identify each instrument. If not checked, *IDN? is sent to all instruments without operator confirmation. You may want the confirmation dialog if your system contains old, non-IEEE-488.2 instruments.


HC_InstrMgrDlgSettingsId

If Ask before sending... is checked, a confirmation dialog is presented before *IDN? is sent to identify each instrument. If not checked, *IDN? is sent to all instruments without operator confirmation. You may want the confirmation dialog if your system contains old, non-IEEE-488.2 instruments.


HC_PrefsAutoLineRoute

When Auto Line Routing is checked, the lines between objects are automatically rerouted when an object is connected, moved, or resized. Auto-routing uses only horizontal and vertical lines, and gives the same results as Edit [image] Clean Up Lines. When auto-routing is off, lines are drawn directly from pin to pin, often diagonally.


HC_PrefsBinaryRunTime

When Binary RunTime File Format is checked, .vxe files are saved using a binary format which gives improved security and smaller file size. When this box is not checked, .vxe files are stored in ASCII format (similar to .vee files).


HC_PrefsCheckAddrs

When instrument checking is enabled, VEE checks the configured instruments during prerun to verify that they are accessible. If an address does not respond, you are given the opportunity to power-on the instrument, choose a different bus address, etc. When this box is not checked, disconnected or improperly configured instruments will probably cause a timeout error when the program is running.


HC_PrefsColors

The Appearance Property Group allows you to choose the default color for any screen element in your VEE program.


HC_PrefsDelVars

When Delete Variables at PreRun is checked, the values stored in all variables are deleted before each program runs. Therefore, Get Variable objects will error if their values have not been properly set. When this box is not checked, Get Variable objects can access old data left from the previous program run. Such old data may or may not be valid for the new program run.


HC_PrefsDisableDebug

When Disable Debug is checked, all debugging features are disabled, giving the fastest program execution speed.


HC_PrefsExecMode

The Execution Mode selection can be used to force backward compatibility for certain programs written in older versions of VEE. Execution Mode is stored with a VEE program, and can be changed in the Default Preferences dialog.

If the Execution Mode is set lower than the current version, the program cannot use newer VEE features. Using the highest possible Execution Mode is recommended, except in the rare cases when the higher mode causes program behavior to change in undesirable ways.


HC_PrefsFlowRate

Sets the speed at which the Data Flow markers move. Select a rate from 1 to 10. The default is 6 and the fastest is 10.


HC_PrefsFonts

The Fonts tab allows you to choose the default font for any screen element in your VEE program.


HC_PrefsNumberFormat

The Number tab allows you to choose the default format for displaying numbers in your VEE program.


HC_PrefsOKButton

When OK is pressed, any changes to Default Preferences become valid for the current work session only. When you exit and restart VEE, the previous Default Preferences (saved in the "vee.rc" file) are restored.


HC_PrefsPrintCover

When Print Cover Page is checked, a cover section is generated at the beginning of the printout. This default format choice can be overridden in the Print Program dialog.


HC_PrefsPrintDarkness

The B&W Printer Darkness setting allows you to choose a shade of gray for each screen element in your VEE program. This shade of gray is used when you print the program on a non-color printer. (The settings in the Appearance Property Group are used for a color printer.)


HC_PrefsPrintExplorer

When Print Program Explorer is checked, the printout includes the overview information contained in the Program Explorer window. This default format choice can be overridden in the Print Program dialog.


HC_PrefsPrintHeaderIdx

When Print Header and Index Page is checked, each printout page is given a page number and other header information, and an Index is generated at the end of the printout. This default format choice can be overridden in the Print Program dialog.


HC_PrefsPrintIOConfig

When Print I/O Configuration is checked, the printout includes the expanded tree view of the I/O configuration (from the Instrument Manager). This default format choice can be overridden in the Print Program dialog.


HC_PrefsPrintMag

Specifies the magnification used when printing a VEE program. Smaller numbers create a smaller image. The value you specify might be rounded by some printer drivers.


HC_PrefsResetButton

When Reset is pressed, any pending changes to Default Preferences are discarded, and the previous Default Preferences (saved in the "vee.rc" file) are restored.


HC_PrefsSaveButton

When Save is pressed, any changes to Default Preferences become valid for the current work session and are saved in the "vee.rc" file. When you exit and restart VEE, the new saved Default Preferences are used. (The exact path to the "veer" file is system dependent.)


HC_PrefsSpacing

Specifies the number of pixels placed between objects when you perform an Edit [image] Align... operation. This Alignment Spacing value is used only when Space Equally is enabled.


HC_PrefsTrigMode

The Trig Mode selection chooses the default trigonometric units used in the program. Radians are VEE's natural (fastest) units.


HC_PrefsWebEnable

When Enable Server is checked, VEE's built-in Web server is activated. The Web server allows you to monitor a VEE program from a remote Web browser.


HC_PrefsWebLogFile

Specifies the file path to the http.log file. This file records all incoming requests processed by the Web server and can grow without bounds.


HC_PrefsWebPortNum

Specifies the port number used by VEE's Web server. This port number must be allocated in your system's services file and must not be used by any other Web server.


HC_PrefsWebRootDir

Specifies the local directory that will be accessible to the remote Web browser. VEE uses the file index.html in the Root Directory as its home page. A default home page is installed as ~installDir/www/index.html. This file can be modified and/or copied to a different Root Directory.


HC_PrefsWebTimeout

Specifies the maximum time (in seconds) that the Web server will wait for VEE to respond.


HC_PrintPrgCover

When this box is checked, a cover section is generated at the beginning of the printout.


HC_PrintPrgExplorer

When this box is checked, the printout includes the overview information contained in the Program Explorer window.


HC_PrintPrgHeaderIdx

When this box is checked, each printout page is given a page number and other header information, and an Index is generated at the end of the printout.


HC_PrintPrgIOConfig

When this box is checked, the printout includes the expanded tree view of the I/O configuration (from the Instrument Manager).


HC_PrintPrgNested

When this box is checked, the printout includes an open view of all nested UserObjects.


HC_PrintPrgObjects

When this box is checked, the printout includes a detailed view of each object in the program. All but the simplest objects are printed in open view form.


HC_ProfilerClear

The Clear button resets all Profiler data values to 0 (zero).


HC_ProfilerCommas

When this box is checked, data is written to the data file with commas as delimiters (separators) between the various Profiler data fields. Using comma delimiters makes it easier to import the data into some other applications, such as spreadsheets. When this box is not checked, the data fields are aligned using multiple spaces.


HC_ProfilerFileName

This field specifies the file name where Profiler data is saved. Click this field to bring up the Save data filename dialog box.


HC_ProfilerNumDigits

This field specifies the number of digits displayed to the right of the decimal point.


HC_ProfilerOnlyExecuted

When this box is checked, Profiler data is shown only for those UserObjects and UserFunctions that executed.


HC_ProfilerOptions

The Options button brings up the Profiler Options dialog box. These options customize the format of displayed and saved data.


HC_ProfilerOverwrite

When this box is checked, each click of the Save button overwrites the data previously saved in the Profiler data file. When this box is not checked, each Save appends to the existing data.


HC_ProfilerRefresh

Profile data is collected whenever the Profiler is running, but the data displayed in the dialog box is not updated automatically. You must click the Refresh button to cause the Profiler to display the latest profile data.


HC_ProfilerResults

When the Profiler is started, it provides comparative information about the execution time of each UserObject and UserFunction. Clicking on any column label (such as Name, or Time) displays the Profiler data sorted on that field. Clicking again reverses the sort. Double-click on any UserObject or UserFunction shown in the Name field, and its view opens in the VEE workspace.


HC_ProfilerSave

The Save button writes the Profiler data to the file name specified using the Options button.


HC_ProfilerStart

The Start Profiling button is a toggle function that starts or stops profiling.


HC_SaveAsDlgColorsFonts

Save colors and fonts with program saves all the default colors and fonts in the program file that are selected in the Default Preferences dialog box. This ensures that whoever opens your program will also get all of your default colors and fonts. If this option is not selected, only the colors and fonts explicitly set in your program are saved in your program file. This allows others using your program to retain their own default colors and fonts. If an existing program is loaded, the option is set according to how the program was saved previously.


HC_SaveAsDlgDeviceConfig

Save I/O configuration with program saves the veeio I/O configuration information with the program file, and not in the veeio resource file. The configuration information is specified in the Instrument Manager. If this option is not selected, the current program's configuration information is saved in the veeio file. If an existing program is loaded, the option is set according to how the program was saved previously.


HC_StatusExecMode

This field shows the Execution Mode of the currently loaded VEE program. Execution Mode allows newer versions of VEE to run older VEE programs with complete backwards compatibility. The possible modes are VEE 3, VEE 4, etc. up through the current VEE version. Execution Mode is saved with the VEE program and can be changed in the Default Preferences dialog.


HC_StatusModified

This field indicates if the currently loaded program has any unsaved changes (modifications). When the box is "grayed out," no unsaved changes are pending.


HC_StatusMsg

The bottom line of the VEE window is a status message area. This status line shows various types of information, depending upon the current operation. For example, the program run state, error messages, pixel position of moved objects, and helpful hints.


HC_StatusProfiler

This field indicates if Profiling is currently enabled. When the box is "grayed out," profiling is stopped.


HC_StatusWebServer

This field indicates if the VEE Web Server is currently enabled. When the box is "grayed out," the Web Server is disabled. The VEE Web Server is controlled in the Default Preferences dialog.


GPIB Instrument Properties

The following properties are programmatically accessible for instruments connected via a GPIB interface.

Property Data Type Description

address | Int16 | The VEE-style I/O address for this instrument. For example: 723
enableEOI | Text | Enable EOI on last byte of write transactions. zero = enable; non-zero = disable. Default is disabled.
eolSequence | Text | The character sequence that is sent at the end of a write transaction. Default is a new-line character.
hostname | Text | Remote server's hostname or IP address (if applicable).
interfaceType | Text | Returns "GPIB" for GPIB instruments.
pnpResource | Text | The VISA-style I/O address for this instrument. For example: GPIB0::23::INSTR
readTerm | Int32 | The character that will terminate a read transaction. Default is a new-line character.
timeout | Real64 | Transaction timeout value in seconds. Default is 5 seconds.

Location

Device [image] Function & Object Browser [image] Instruments

See Also

Instrument Manager, GPIO Instrument Properties, Serial Instrument Properties, VXI Instrument Properties.


GPIO Instrument Properties

The following properties are programmatically accessible for instruments connected via a GPIO interface.

Property Data Type Description

address | Int32 | The VEE-style I/O address for this instrument. For example: 12
eolSequence | Text | The character sequence that is sent at the end of a write transaction. Default is a new-line character.
hostname | Text | Remote server's hostname or IP address (if applicable).
interfaceType | Text | Returns "GPIO" for GPIO instruments.
pnpResource | Text | Not applicable for GPIO.
readTerm | Int32 | The character that will terminate a read transaction. Default is a new-line character.
timeout | Real64 | Transaction timeout value in seconds. Default is 5 seconds.

Location

Device [image] Function & Object Browser [image] Instruments

See Also

Instrument Manager, GPIB Instrument Properties, Serial Instrument Properties, VXI Instrument Properties.


Serial Instrument Properties

The following properties are programmatically accessible for instruments connected via a serial (RS-232) interface.

Property Data Type Description

address | Int32 | The VEE-style I/O address for this instrument. For example: 9
baudRate | Int32 | Current Baud rate of the RS-232 interface. Default is 9600.
charSize | Int32 | Data bits per character frame. Can be 5 through 8. Default is 8.
eolSequence | Text | The character sequence that is sent at the end of a write transaction. Default is a new-line character.
handshake | Text | Pacing mechanism for current connection. Can be None, XonXoff, RtsCts, or DtrDsr. Default is none.
hostname | Text | Remote server's hostname or IP address (if applicable).
interfaceType | Text | Returns "Serial" for RS-232 instruments.
parity | Text | Parity bit generation/checking. Can be None, Even, Odd, Mark, or Space. Default is none.
pnpResource | Text | The VISA-style I/O address for this instrument. For example: ASRL0::INSTR
readTerm | Int32 | The character that will terminate a read transaction. Default is a new-line character.
timeout | Real64 | Transaction timeout value in seconds. Default is 5 seconds.

Location

Device [image] Function & Object Browser [image] Instruments

See Also

Instrument Manager, GPIO Instrument Properties, GPIB Instrument Properties, VXI Instrument Properties.


TCPIP Instrument Properties

The following properties are programmatically accessible for instruments connected via a TCPIP interface.

Property Data Type Description

eolSequence | Text | The character sequence that is sent at the end of a write transaction. Default is a new-line character.
hostname | Text | Remote server's hostname or IP address (if applicable).
interfaceType | Text | Returns "TCPIP" for TCPIP instruments.
readTerm | Int32 | The character that will terminate a read transaction. Default is a new-line character.
timeout | Real64 | Transaction timeout value in seconds. Default is 5 seconds.
visaAddress | Text | The VISA address of the device. For example, TCPIP::[Instrument IP Address]::inst0::INSTR

Location

Device [image] Function & Object Browser [image] Instruments

See Also

Instrument Manager, GPIO Instrument Properties, Serial Instrument Properties, VXI Instrument Properties.


USB Instrument Properties

The following properties are programmatically accessible for instruments connected via a USB interface.

Property Data Type Description

eolSequence | Text | The character sequence that is sent at the end of a write transaction. Default is a new-line character.
hostname | Text | Remote server's hostname or IP address (if applicable).
interfaceType | Text | Returns "US B" for USB instruments.
readTerm | Int32 | The character that will terminate a read transaction. Default is a new-line character.
timeout | Real64 | Transaction timeout value in seconds. Default is 5 seconds.
visaAddress | Text | The VISA address for the instrument. For example, USB0::2391::1031::123456789::0::INSTR
visaAlias | Text | The VISA alias for the instrument. The visaAddress is very long and awkward to work with, so an alias is used to make working with the instrument much easier.

Location

Device [image] Function & Object Browser [image] Instruments

See Also

Instrument Manager, GPIO Instrument Properties, Serial Instrument Properties, VXI Instrument Properties.


VXI Instrument Properties

The following properties are programmatically accessible for instruments connected via a VXI interface.

Property Data Type Description

address | Int32 | The VEE-style I/O address for this instrument. For example: 16
enableEOI | Int16 | Enable EOI on last byte of write transactions. zero = enable; non-zero = disable. Default is disabled.
eolSequence | Text | The character sequence that is sent at the end of a write transaction. Default is a new-line character.
hostname | Text | Remote server's hostname or IP address (if applicable).
interfaceType | Text | Returns "VXI" for VXI instruments.
pnpResource | Text | The VISA-style I/O address for this instrument. For example: VXI0::24::INSTR
readTerm | Int32 | The character that will terminate a read transaction. Default is a new-line character.
timeout | Real64 | Transaction timeout value in seconds. Default is 5 seconds.

Location

Device [image] Function & Object Browser [image] Instruments

See Also

Instrument Manager, GPIO Instrument Properties, Serial Instrument Properties, GPIB Instrument Properties.


LAN Gates

LAN Gateways

VEE can access LAN gateways to control instruments. A LAN gateway is a controller that allows access to its VXI, GPIB, GPIO, and Serial interfaces and the instruments on these interfaces from a remote process.

The client-server model best represents the arrangement. A VEE process acts as the client when accessing a LAN gateway on a remote computer, the server. The server has a committed process, known as a daemon, which is part of the SICL process running on the server. The daemon communicates with the VEE client and allows access to its interfaces and their devices.

The client process calls SICL in order to control devices on the interfaces that SICL supports. These interfaces are usually configured on the LAN gateway on which the SICL process is running. By using the LAN gateway, these interfaces can be on a remote computer.

As far as the client is concerned, the fact that the interfaces and their devices are attached physically to a remote computer is invisible.

Configuration

You must configure VEE and the LAN hardware to use the LAN gateway.

VEE Configuration Configure VEE for gateway access during device configuration, as described in Details of the Properties Dialog Boxes. The Instrument Properties dialog box is shown below. The Gateway field shows its default setting, This host:

You can select the gateway name by clicking the Gateway field. A list box appears showing all of the gateways that have been configured previously. This host always points to the computer on which VEE is running.

If there are no other choices for gateways, you can type in a gateway name. The name must be resolvable to an IP address either by a symbolic host name table or by a name-server. You can also enter an IP address in dot-format, such as 55.55.55.555.

Beyond selecting a gateway, the configuration process remains the same. Panel Driver and Direct I/O objects are configured as before. Various I/O devices configured for interfaces and devices on remote computers are shown below.

LAN Hardware Configuration The SICL LAN gateway support depends on the configuration of the machine on which VEE is running, the machine on which the gateway daemon is running, and the overall configuration of the LAN. Consult with your system administrator to configure the LAN and ensure that names and IP addresses are resolvable.

For the machine running the gateway daemon, it is assumed that the daemon install procedures will configure the local networking files correctly. If you are using the E5810A LAN/GPIB Gateway, it is self-contained and all internal configuration is done.

Execution Behavior

Ideally, I/O operations through the gateway work as if the interfaces and devices are attached directly to the client computer. However, response times can vary, depending on the LAN configuration, including the number of connected hosts, LAN-to-LAN gateways, and current load. Sometimes, a connection is terminated by disconnected cables or computer failures on the LAN. These events must be accommodated when configuring timeout periods.

When the server receives an I/O request from the client application, VEE, the server uses the timeout value that you enter in the Instrument Properties dialog box. This is called the SICL timeout. If the server's operation is not completed in the specified time, the server sends a reply to the client indicating that a timeout occurred and the normal VEE timeout error occurs.

When the client sends an I/O request to the server, the client starts a timer and waits for the reply from the server. If the server does not reply in time, a timeout occurs and a VEE timeout error is produced. This is called the LAN timeout.

The client timeout differs from the server timeout because the I/O transaction time for the server is usually different from the transmission time over the LAN. The server may complete an I/O transaction within five seconds (the VEE default timeout period), but the actual transmission over the LAN back to the client may take longer than five seconds.

The two timeouts are separate values that are adjusted using two entries in the SICL configuration file:

sicl_infinity | Used by the server if the user-defined timeout (the SICL timeout), entered in the Advanced Instrument Properties dialog box, is infinity (0). The server does not allow an infinite timeout period. The value specifies the number of seconds to wait for a transaction to complete within the server.
lan_timeout_delta | Value added to the server's timeout value to determine the client's timeout period (LAN timeout). The calculated LAN timeout only increases as necessary to meet the needs of the I/O devices, and never decreases. This avoids the overhead of readjusting the LAN timeout every time the SICL timeout changes.


No Help Topic Available

The Help topic for this object or dialog box is not implemented yet.


NotOnNet

Error

This computer is not connected to the network.

Sorry for any inconvenience.


Polynomial

A menu item.

Use

Use Polynomial to access the following objects which generate a Real64 polynomial result from the data and coefficient values. These objects are summarized as poly(x,vec).

poly(x,[a0, a1])

poly(x,[a0, a1, a2])

poly(x,[a0, a1, a2, a3])

poly(x,[a0, a1, ... aN])

Location

Math [image] Polynomial

See Also

Generate, and poly(x,vec).


Programmatic I/O Configuration

You can programmatically modify your instrument configuration. The preferred way of programing the I/O configuration is to use the programmatic instrument configuration in the Function and Object Browser. The browser window with Instruments selected, selecting Instruments activates the Create Set Formula button at the toolbar.

Clicking Create Set Formula brings up the Formula Object dialog box.

Previous versions of VEE allowed programmatic configuration through control pins. These pins are obsolete but still supported for legacy SICL style interfaces for GPIB and Serial. Control pins are available for the Panel Driver, Component Driver, and Direct I/O instrument control objects that let you input other values for device address and timeout. Control pins for setting timeout values are also available for the Interface Operations, Instrument Event, and Interface Event objects.

When a new timeout or address is sent to one of the control pins, the new value is changed globally for that device. This means that all instrument control objects communicating with a particular device begin using the new timeout or address value. The new value can be different from that entered in the Instrument Properties dialog box and placed in the VEE configuration file. However, this new value is never written to the VEE configuration file.

The following example shows a Direct I/O object with an Address control pin. The HP E1413B is originally configured for address 16032 as shown in the title bar. The input to the control pin is 16040 (the new address). When the control pin is sent the new address, 16040 is used for any other objects communicating with the HP E1413B.

See Also

To Change Interface Dynamically


Protecting Critical Sections

In a multi-process test system, sharing a resource among the processes requires a locking mechanism to protect critical sections. A critical section is needed when one of the processes needs exclusive access to a shared instrument resource.

To prevent another process from accessing the instrument during the critical section, the first process locks the instrument. The lock remains in effect for the time necessary to complete its task. During this time, the second process cannot execute any interaction with the instrument, including an attempt to lock the instrument for its own use.

The following EXECUTE transactions let you protect critical sections and can be used in the Direct I/O, MultiInstrument Direct I/O, and Interface Operations transaction objects. The transaction syntax varies depending on the interface and transaction object being used. For GPIB, Serial, and GPIO, the entire interface is locked. For VXI, individual devices are locked.

To lock VXI devices via direct backplane access in the Direct I/O object, use the transactions:

   EXECUTE LOCK DEVICE

EXECUTE UNLOCK DEVICE

In the MultiInstrument Direct I/O object, use the transactions:

   EXECUTE vxiScope LOCK DEVICE

EXECUTE vxiScope UNLOCK DEVICE

where vxiScope is the configured name of a VXI oscilloscope such as the HP E1428B.

To lock GPIB, Serial, and GPIO Interfaces in the Interface Operations object, use the transactions:

   EXECUTE LOCK INTERFACE

EXECUTE UNLOCK INTERFACE

Supported Platforms (EXECUTE LOCK/UNLOCK)

Platform | Supported I/O Interfaces
Windows 2000, Windows XP, Windows Vista | USB, TCP/IP, VXI (PC with VXLink, or embedded)a

a Register and memory access of VXI devices (READ/WRITE REGISTER/MEMORY transactions) are not lockable. Only the very first execution of a transaction that attempts a direct memory access could be locked out if the memory is mapped into the VEE process space) by a prior lock in another process. After that, there is no way to prevent multiple processes from simultaneously accessing a memory location since this is shared memory.

Execution Behavior

When a version of the EXECUTE LOCK transaction executes, it tries to acquire a lock on the device or interface. If there is no pre-existing lock owned by another process, the transaction executes completely and the lock acquisition succeeds. If a prior lock exists, the transaction blocks for the current timeout configured for that device or interface.

If the other process gives up the lock within the timeout period, the transaction completes and acquires the lock. If the timeout period lapses, an error occurs and an error message box appears. This error can be captured by an error pin on the transaction object.

After the lock is acquired, all subsequent I/O from Direct I/O, MultiInstrument Direct I/O, Panel Driver, Component Driver, and Interface Operations objects are protected from any other process attempting to communicate to that device or interface.

After the critical section has passed, the corresponding version of the EXECUTE UNLOCK transaction can be executed.

Locks only protect critical sections across process boundaries. A single process can create nested locks by performing two EXECUTE LOCK transactions in sequence. Both transactions will succeed as long as there are no prior locks by another process.

The process must then perform two EXECUTE UNLOCK transactions. If only one EXECUTE UNLOCK transaction is executed the device or interface remains locked. If a transaction attempts an unlock without a prior lock, a run-time error occurs.

Locks only exist while the VEE program is executing. When a VEE program finishes executing, all locks are removed from devices and interfaces. This protects the user from leaving devices or interfaces locked if the program stops executing due to normal completion, run-time errors, or a pressed Stop button, and no EXECUTE UNLOCK transaction has executed.

Example: EXECUTE LOCK/UNLOCK Transactions - VXI

The next example program shows the EXECUTE LOCK/UNLOCK DEVICE transactions in a MultiInstrument Direct I/O object. You could use the Direct I/O object instead of the MultiInstrument Direct I/O, but that would mean using an object for each device instead of one object for the group of devices. A For Count object drives a thread which tries to acquire locks on three different devices. After the I/O activity is done in the UserObjects, a series of unlocks are executed.

Each transaction tries to acquire its respective lock for the timeout period configured for each device. If any of the three transactions timeout, an error occurs that is trapped by the error pin. If a successful lock is followed by an attempt resulting in a timeout error, the error pin traps the error.

Before the program can re-execute the lock transactions, all acquired locks must be unlocked. That is why the MultiInstrument Direct I/O object is attached to the error pin. It is very important that this object try to unlock each device in the same order as the first object acquired the locks.

Since an error occurs if an unlock transaction is executed before the lock transaction, an error pin is also added to the object with the unlock transactions. If a transaction fails to acquire the lock in the first object, the same unlock transaction fails in the following object.


RGB Values for Agilent VEE Colors

Use these RGB values when you're making a custom bitmap and need to match a VEE color, for example, to match a panel background color.

This list of colors and their RGB values may change in future releases of VEE

Black | r:0 | g:0 | b:0
Dark Beige | r:105 | g:95 | b:80
Darkest Gray | r:96 | g:96 | b:96
Dark Gray | r:128 | g:128 | b:128
Med Dark Gray | r:160 | g:160 | b:164
Gray | r:192 | g:192 | b:192
Med Light Gray | r:208 | g:208 | b:208
Light Gray | r:224 | g:224 | b:224
Lightest Gray | r:240 | g:240 | b:240
White | r:255 | g:255 | b:255
Darkest Red | r:121 | g:0 | b:21
Dark Red | r:128 | g:0 | b:0
Med Red | r:207 | g:14 | b:48
Warning Red | r:230 | g:30 | b:30
Red | r:255 | g:0 | b:0
Light Warning Red | r:229 | g:64 | b:93
Med Light Red | r:247 | g:102 | b:129
Light Red | r:255 | g:128 | b:128
Med Pale Red | r:253 | g:164 | b:181
Pale Red | r:255 | g:197 | b:207
Darkest Orange | r:113 | g:32 | b:0
Dark Orange | r:188 | g:55 | b:0
Med Dark Orange | r:243 | g:91 | b:27
Med Orange | r:245 | g:123 | b:73
Orange | r:255 | g:128 | b:0
Golden Orange | r:239 | g:145 | b:0
Light Orange | r:255 | g:162 | b:124
Light Golden Orange | r:246 | g:191 | b:105
Pale Orange | r:252 | g:209 | b:193
Pale Golden Orange | r:253 | g:227 | b:186
Dark Brown | r:96 | g:64 | b:64
Med Brown | r:113 | g:68 | b:0
Golden Brown | r:163 | g:105 | b:0
Dark Gold | r:149 | g:108 | b:54
Brown | r:150 | g:110 | b:75
Gold | r:176 | g:145 | b:91
Beige | r:148 | g:139 | b:123
Golden Beige | r:175 | g:160 | b:126
Light Gold | r:203 | g:182 | b:128
Light Beige | r:220 | g:211 | b:184
Darkest Yellow | r:78 | g:79 | b:0
Darkest Green Yellow | r:118 | g:121 | b:0
Dark Green Yellow | r:150 | g:150 | b:0
Med Green Yellow | r:179 | g:185 | b:0
Dark Yellow | r:192 | g:192 | b:0
Med Dark Yellow | r:213 | g:213 | b:45
Med Yellow | r:234 | g:236 | b:94
Yellow | r:255 | g:255 | b:0
Light Yellow | r:255 | g:255 | b:128
Pale Yellow | r:252 | g:254 | b:185
Dark Green | r:0 | g:96 | b:0
Forest Green | r:49 | g:101 | b:1
Med Dark Green | r:0 | g:130 | b:70
Med Green | r:67 | g:142 | b:0
Green | r:0 | g:193 | b:19
Med Yellow Green | r:64 | g:229 | b:10
Yellow Green | r:128 | g:255 | b:0
Light Yellow Green | r:163 | g:242 | b:95
Light Green | r:128 | g:255 | b:128
Pale Green | r:219 | g:255 | b:184
Darkest Teal | r:0 | g:78 | b:71
Med Dark Teal | r:0 | g:107 | b:97
Dark Teal | r:0 | g:128 | b:128
Med Teal | r:0 | g:150 | b:136
Teal | r:0 | g:160 | b:160
Med Light Teal | r:0 | g:183 | b:165
Light Teal | r:0 | g:192 | b:192
Blue Gray | r:120 | g:184 | b:210
Cyan | r:0 | g:255 | b:255
Pale Cyan | r:140 | g:244 | b:234
Dark Blue | r:0 | g:0 | b:128
Med Dark Blue | r:70 | g:0 | b:240
Blue | r:0 | g:0 | b:255
Dark Sky Blue | r:51 | g:101 | b:251
Med Light Blue | r:0 | g:128 | b:255
Lavender | r:128 | g:128 | b:255
Light Blue | r:96 | g:192 | b:255
Sky Blue | r:162 | g:193 | b:254
Pale Blue | r:193 | g:206 | b:255
Light Blue Gray | r:195 | g:211 | b:219
Darkest Purple | r:80 | g:0 | b:147
Dark Purple | r:90 | g:0 | b:170
Med Purple | r:123 | g:0 | b:228
Purple | r:128 | g:0 | b:255
Violet Purple | r:146 | g:52 | b:219
Light Violet Purple | r:183 | g:96 | b:249
Med Light Purple | r:200 | g:120 | b:253
Light Purple | r:212 | g:159 | b:255
Med Pale Purple | r:227 | g:190 | b:255
Pale Purple | r:240 | g:210 | b:255
Dark Magenta | r:128 | g:0 | b:128
Dark Pink Magenta | r:181 | g:0 | b:105
Hot Pink | r:255 | g:0 | b:128
Light Pink Magenta | r:217 | g:49 | b:146
Med Magenta | r:236 | g:24 | b:200
Magenta | r:255 | g:0 | b:255
Light Magenta | r:255 | g:128 | b:255
Pink | r:255 | g:128 | b:192
Light Pink | r:243 | g:159 | b:209
Pale Pink | r:253 | g:192 | b:229


Set Last File Write Time

Sets the last file write time for the given file.

Location

System [image] File [image] Set Last File Write Time


Tab Index

Active only on Panel view, Tab Index lets you set the tab order for Objects on the Panel.

Use

Accessed through the Properties Window, the Tab Index lets you set the tab order of the Objects on the Panel view. This is very useful when operators have only a keyboard.

See Also

Panel View Navigation Techniques

To Change Properties Programmatically

Programmatic Properties


General Tips

When developing your program, use a screen resolution the same as (or similar to) the destination system. The Panel View is a specific-sized window (by the number of pixels) that does not scroll. You need to make sure that the Panel View will fit on the destination system's screen.

You can specify the size of the VEE Window before you create it. When you start VEE, use the command line option -geometry, to specify the size of the Detail View, and therefore specifying the size of the Panel View when it is created. For information about using command-line options, see To Start Agilent VEE with Command-Line Options.

If there are multiple destination system types, when developing your program use a system that is the lowest common denominator so you can get a realistic feel for the worst case for resolution (text readability), execution speed, and color use.

Test your program on the destination system before finalizing the program.

There may be keyboard differences that are important when giving instructions to your user. For example, Esc may be in a different location on the keyboard.

Don't use binary data files. Save data files as ASCII.


To Create a UserFunction in a Program

The following example shows, step-by-step, how to create a simple UserFunction and connect it in a VEE program. Ideally, the objects used together in a UserFunction should perform a particular task.

1. Add a UserFunction to the Main work area (Device UserFunction). A UserFunction edit window appears.

2. Add objects to the UserFunction work area, and connect the terminals between them as needed. You can use the same techniques to add objects to a UserFunction as described in To Add Objects to the UserObject Work Area.

3. Add and connect the input and output terminals for the UserFunction:

a. Place the mouse cursor in the input terminal area of the UserFunction and press Ctrl+A. The data input terminal appears in the edit window’s terminal area.

b. In the edit window, connect the inside pin of the input terminal to the appropriate object inside the UserFunction.

c. Place the mouse cursor in the output terminal area of the UserFunction and press Ctrl+A. The data output terminal appears in the edit window’s terminal area.

d. In the edit window, connect the inside pin of the output terminal to the appropriate object inside the UserFunction.

4. Change the UserFunction title to a descriptive name so you can identify it in the program. Double-click the title bar on the UserFunction edit window. In the Properties Window dialog box, type in a new title. The title cannot contain spaces.

5. Add a Call object to your program. In the UserFunction edit window’s object menu, click on Generate Call. A Call object appears with the title and terminals corresponding to those added to the UserFunction.

Depending on the UserFunction’s purpose, you may want to generate a call to it from one of the other objects in the Generate menu.

6. Connect lines to the input and output terminals on the Call object.

7. Run the program to test the UserFunction.

The following example shows a program with the UserFunction edit window open.

See also

To Build a UserFunction Panel

To Call a UserFunction in a Program

To Create a UserFunction from Objects in a Program

To Edit a UserFunction

UserFunction

To Call a UserFunction from an Expression


To Iterate a Record


VEE Lady

The VEE Lady is the undisputed authoritative expert on Agilent VEE Pro, as those who have disputed this are no longer able to do so. (Even the VEE Answer Man avoids her at all cost.) While some have characterized the VEE Lady as callous, rude, and condescending, others simply call her crass, belligerent, brash, and conceited. Although her VEE technical prowess is second to none, the VEE Lady's physical appearance is so hideous that it has been known to turn people to stone. Only protective eye wear for the cast and crew and a special shielding mask on the VEE Lady let us bring you the Queen of VEE at all.


Welcome to Agilent VEE Express

Welcome!

Welcome to Agilent VEE Express Help. To find a topic you want to read, click on the Contents or Index buttons above.

Because Agilent VEE Express 8.5 is a subset of Agilent VEE Pro 8.5, we provide the same online help as that of Agilent VEE Pro 8.5. Some of the pages in online help may refer to a feature that does not exist in Agilent VEE Express. Please read About Agilent VEE Express 8.5 on the differences between the two products.

Agilent VEE Pro 8.5 New Features

What Has Been Fixed in This Release

Microsoft®, MS-DOS®, Windows®, MS Windows®, Windows NT®, Excel®, Word®, .NET®, Outlook®, ActiveX®, Visual Basic®, Visual C# ® are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries.

PostScript® is a trademark of Adobe Systems Incorporated.

MATLAB® is a registered trademark of The MathWorks, Inc.

National Instruments®, NI®, LabVIEW® and SCXI® are registered trademarks of National Instruments Corporation.

PXI® is a registered trademark of PXI System Alliance.

IVI® and IVIplug&play® are registered trademarks of the IVI Foundation.

Pentium® is a U.S. registered trademark of Intel Corporation.

Arial® and Times New Roman® are U.S. registered trademarks of the Monotype Corporation.


Welcome to Agilent VEE Student

Welcome!

Welcome to Agilent VEE Student Help. To find a topic you want to read, click on the Contents or Index buttons above.

Because Agilent VEE Student 8.5 is a subset of Agilent VEE Pro 8.5, we provide the same online help as that of Agilent VEE Pro 8.5. Some of the pages in online help may refer to a feature that does not exist in Agilent VEE Student. Please read About Agilent VEE Student on the differences between the two products.

Agilent VEE Pro 8.5 New Features

What Has Been Fixed in This Release

Microsoft®, MS-DOS®, Windows®, MS Windows®, Windows NT®, Excel®, Word®, .NET®, Outlook®, ActiveX®, Visual Basic®, Visual C# ® are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries.

PostScript® is a trademark of Adobe Systems Incorporated.

MATLAB® is a registered trademark of The MathWorks, Inc.

National Instruments®, NI®, LabVIEW® and SCXI® are registered trademarks of National Instruments Corporation.

PXI® is a registered trademark of PXI System Alliance.

IVI® and IVIplug&play® are registered trademarks of the IVI Foundation.

Pentium® is a U.S. registered trademark of Intel Corporation.

Arial® and Times New Roman® are U.S. registered trademarks of the Monotype Corporation.


What’s New in previous versions

Version Information

Noted below are the new features and enhancements for versions 5. , 6.0, 7.0, 7.5, 8.0. To go to a specific version, select one of the links below.

Version 8.0

Version 7.5

Version 7.0

Version 6.0
Version 5.0

Agilent VEE Pro 8.0 New Features

Watch Window

Watch Window allows the user to view and edit values of variables and terminals when debugging. The program can continue execution incorporating any changed values.

When you click [image] button on Toolbar, or select View [image] Watch Window, the Watch Window dialog box appears as follows.

See Watch Window for more information.

Examples

Datatype.vee, Globals.vee, Terminals.vee

Code Completion and Code Insight

Code Completion and Code Insight greatly benefits any user who writes formula objects by reducing keyboard inputs and the need for memorization and external documentation. You can stay in your context, find the information you need, insert language elements directly into your formula, and even have Agilent VEE complete your typing for you. See Code Completion and Code Insight for more information.

Color Syntaxing

1. Comments are marked Green, Constant Strings are marked Dark Red and keywords are marked Blue.

2. Errors in a formula are marked by red wave lines.

3. Brackets are marked by grey frames.

Objects Supported by Code Completion and Code Insight

Objects Supported

Code Completion

  • .NET objects

  • Named VEE Objects

  • COM objects

  • Built-in Constants

  • Built-in Functions

  • Records

Code Insight

  • Member functions of .NET and COM objects

  • Local UserFunctions

  • Imported UserFunctions

  • Built-in Functions

  • Imported Remote Functions

  • Imported Compiled Functions

Programmatic Properties

Programmatic properties helps the user to create better GUI faster. It allows users to GET/SET properties of VEE Objects, .NET objects, and COM objects at runtime. See ProgrammaticPropertyDemo.vee for a quick demo of this powerful new feature.

The following table shows properties that can be SET/GET programmatically. See To Change Properties Programmatically and To Change Object's Name and Scope for more detail information

Example

ProgrammaticPropertyDemo.vee DemoTabIndexChangeDemo.vee

Minimap

Minimap is an outline map of the entire detail view with a red rectangle box indicating the visible portion. To open the Minimap, click [image] button on Toolbar or choose View [image] Minimap. An example of Minimap is shown in the following figure.

The red rectangle shows the relative location of the visible area in the entire detail view. Just one click on the Minimap, you can quickly jump to another location in the detail view. See Minimap for more detail information.

Home button

Agilent VEE 8.0 adds a new Toolbar button Home [image], which moves the upper left corner of a program to the upper left corner of the context (Main, UserFunctions, or UserObjects).

New Execution Mode and Data Types

Beginning with version 8.0, Agilent VEE supports two new data types - Int64 and Boolean and a new Execution Mode - VEE 8.

Although the user can use TRUE and FALSE as constants since version 5.0, TRUE and False are not real Boolean constants. They are of Int32 type. From Agilent VEE 8.0, the two constants will be of real Boolean type. The supported logical operations in Agilent VEE 8.0 are AND, OR, NOT, XOR, ==, and !=. Agilent VEE 8.0 also supports Boolean in Compiled Functions. The user can use VEE_BOOL as the return type and the parameter type of a Complied Function. VEE_BOOL is treated as Boolean. See Boolean for more information.

New menu items and built-in functions added for Boolean:

  • Data => Constant => Boolean

  • Data => Constant => Boolean Array

  • Data => Alloc Array => Boolean

  • asBoolean(x)

Int64 has the longest precision for representing an integer. Agilent VEE provides two built-in numeric constants to represent the maximum and minimum values of int64: MaxInt64 and MinInt64. Constants in different Execution Modes will be explained as different types. See Int64 for more information.

New menu items and built-in functions added for Int64:

  • Data => Constant => Int64

  • Data => Constant => Int64 Array

  • Data => Alloc Array => Int64

  • asInt64(x)

Standardize on VISA Style Devices

Phase out older inconsistent I/O devices (mixed SICL & VISA) for a more uniform approach (VISA) when declaring/using I/O devices. Backward compatibility is maintained, even though users are "encouraged" to use new-style devices. See here for detail information.

Display Multiple Traces on Graph Objects through a Single Input Pin

This feature allows the user to display multiple traces (an array of traces) with the Agilent VEE Graph objects without knowing how many traces there will be ahead of time.

A new Boolean Graph property is added called 'MatrixInput' in detail view properties. When this MatrixInput property is set to True, the Agilent VEE Graph object would accept a 2D Array (up to 12 rows) as Input data and display multiple traces simultaneously. The Data container comes into a graph on a single input pin. The graph figures how many traces are contained there (up to 12 rows), shows the appropriate number of trace legends, and plots their points (columns). This new property CANNOT be toggled at runtime programmatically. The user must know when they are building their Agilent VEE program whether they need this new-style graph.

For detail information, please see example program 2dXyTrace.vee, MatrixInputStripChart.vee.

Multiple Transaction Enhancements

In Agilent VEE 8.0, rich new features have been added for all transaction-based objects (e.g., Direct I/O objects, To/From objects), especially supporting operations on multiple transactions.

Major enhancements include:

* Arbitrarily select, delete, copy, and paste multiple transactions

* Undo/Redo Add/ Insert/ Delete/ Cut/ Paste/ Edit/ Move up/ Move down actions

* All Windows-standard shortcuts

CTRL+X --- Cut the selected transaction(s) to the "cut-and-paste" buffer

CTRL+C --- Copy the selected transaction(s) to the "cut-and-paste" buffer

CTRL+V --- Paste transaction(s) at the pointer location

Delete --- Delete the selected item(s) in the list

Insert --- Insert a transaction before current selected item

CTRL+Z --- Undo last operation

CTRL+Y --- Redo last operation

CTRL+Up --- Move the selected transaction up (only for single-transaction)

CTRL+Down --- Move the selected transaction down (only for single-transaction)

CTRL+ LeftButtons --- Select multiple transactions

Record Usability Enhancement

Agilent VEE 8.0 enhances Record usability in three aspects:

1. Declare Variable now has a Generate context menu for Record data type. The user can generate Record Constant objects, Build Record objects, and Unbuild Record objects.

2. Record Constant object now has a new Generate context menu for Record data type. The user can generate Declare Variable objects or Unbuild Record objects.

3. Added a new Built-in Function: buildRecord (fieldNameTextArray, field1, field2, fieldN)

The user can use buildRecord() to build a record whose field names and values are not known until runtime. The first parameter is an array of strings for the field names. The following parameters are values for each field, and the number of these parameters must match that array length. buildRecord() returns a scalar record with the specified field names and field values. Two examples are as follows:

buildRecord(fieldNameList2Long, field1, field2);

builldRecord(fieldNameList8Long, field1, field2, field3... field8);

See buildRecord() for more information.

NIDAQ Support Updated to Include NIDAQmx Drivers

Agilent VEE 8.0 provides support for new NI's Data Acquisition driver library NIDAQmx. This support includes access to all of the functions in the library and online help for each function. Instruments Manager can find instruments with NIDAQmx drivers automatically.

Allow Scrolling in Panel View

ScrollBars can be set to automatically appear when your panel view is not large enough to display all objects. This feature can be turned on and off by changing the Panel property named "ScrollbarsEnabled". The default is off. See here for detail information.

Instrument Samples

Added 16 new instrument samples in examples\instrumentIO\InstrumentManagerIntegrated.

Updated many Instrument samples.

Agilent VEE Pro 7.5 New Features

Programs saved from VEE Pro 7.0 or 7.5 will not load into prior VEE versions.

Excel Library Add-in

The Excel Library add-in offers simple connectivity between Microsoft Excel and VEE. No more dealing with the awkwardness of ActiveX. The features you want from Excel are now completely exposed for your use using menu picks and options settings. For more information, see Help [image] How Do I [image] Use the VEE Excel Library.

For Each Statement

The For Each statement is similar to the For Count or For Range statements, but it executes the statement block for each element in an array. It supports up to 10 dimensions. For more information, see For Each.

NI Data Acquisition Support (PXI and PCI)

Support for NI's Data Acquisition driver libraries including NI-SWITCH, NI-DMM, NI-SCOPE, NI-DAQ, and NI-FGEN. This support includes access to all of the functions in these libraries and online help for each function. See To/From NIDAQ.

.NET Operation Builder

The .NET Operation Builder makes it very easy to select a .NET Type and subsequently build .NET operations by selecting the methods and properties that are part of it. The operations are generated into a familiar transaction box similar to the existing To/From transaction boxes. Start your tour of this new tool with .NET Operation Builder.

.NET Controls

The .NET Framework provides a rich set of standard controls in the System.Windows.Forms assembly. These controls are easily accessible from VEE using the .NET Controls feature. Just select Device [image] Windows Forms Controls and you see a listing of controls you can add to the VEE work surface. Noted below is a partial listing.

Load a Sample for a Selected Instrument

Select an instrument from the ones in Instrument Manager and choose Load Sample. A list of available samples is presented. After you select a sample, a new session of VEE is launched using the given instrument. The instrument is automatically configured, just press Run to see the sample in action.

Description Indicator

It has been difficult to tell if an object had a description. If you choose to enable this indicator using Default Preferences, a small red triangle appears in the upper right corner of objects that have a description.

IVI-COM and Instrument Manager

IVI-COM is now a driver pick in the Instrument Manager. This makes it much simpler to configure and use IVI-COM drivers for your instruments.

Go To Panel on the Detail Context Menu

There has been an option in the Panel context menu called Go to Detail. This new feature adds a complementary context menu item for the Detail menu called Go To Panel.

Agilent VEE Pro 7.0 New Features

Agilent VEE Pro 7.0 has some new features, such as the Property Grid and Microsoft Visual Studio .NET programmability, that make the VEE Pro 7.0 save format unique. Programs saved from VEE Pro 7.0 will not load into prior VEE versions.

Undo/Redo

One of the most commonly requested features has been Undo. Both Undo and Redo operations will be supported in VEE for many common operations. Examples include: cut a line, delete a terminal, delete objects from a panel, paste objects, move an object, and many more.

See Undo and Redo

Object Property Editing

Using a property editing box similar to what is available in Visual Basic, VEE provides a Properties Window where you can easily change a host of properties for your VEE objects. It's simple and, in most cases, will be two clicks and you're done. It works when you select multiple objects (providing an "intersection" of properties for the two objects if they are different). It works on the detail view and panel view too!

See Properties (Object)

Panel Edit Features

Editing objects on panels just got easier. The following have been added: a visible grid, alignment of objects, "rubber-band" selection of objects, undo of many common operations while building a panel, bring to front, send to back, tab order, and other features as well.

Rich Text Format for Notepad and Description

Editing notes, and descriptions is now much easier. Using the power of .NET, RTF has been implemented for these two. Additionally, the notes and descriptions contain automatic hyperlink detection and bring up a browser with the link you select. Both support undo (CTRL-Z) and redo (CTRL-Y) as well as all your other familiar editing short-cut keys. You can cut and paste from an .rtf file directly into a note or description and word wrap works also. Finally, you can create a custom template (default templates are templates\notepad.rtf and templates\description.rtf). These templates are retrieved whenever you create a new object from the menu. Of course, if you don't want a template, you can always remove it.

Programmatically Use .NET Assemblies

There are a great number of .NET classes available today, and there will be more in the future. Sometimes the functionality these classes provide is not available in VEE or is more desirable than what VEE offers. To make these valuable assets available to you, VEE 7.0 provides access to the Microsoft .NET Framework Library. This Library contains feature rich classes that you can use in a way similar to your use of ActiveX in VEE 5.x and above. See the examples in the DotNet examples directory to get some idea of the power of the .NET Framework to enhance VEE.

An additional feature is the ability to import namespaces. From the Device > .NET Assembly References menu, check the "Import namespaces after closing" checkbox. Choose one or more .NET Assemblies, and you will be prompted to select zero or more namespaces. You can also choose Import .NET Namespaces from the Device menu. What is the significance of this? Well, without a namespace import you might have to type System.IO.File.Exists(). With a namespace import, your method call looks like File.Exists(). Just a few clicks replaces a lot of typing.

A new type conversion function called asClrType has been added. This function converts a VEE data type to a .NET/CLR data type. The valid .NET/CLR data types include all of the primitive data types (Boolean, Byte, SByte, Int16, Int32, Uint32, Int64, Char, Double and Single), Decimal, DataTime, and String. asClrType is rarely needed as VEE converts between VEE and .NET data types automatically most of the time. For an example of VEE program using asClrType, please see examples\dotnet\datetime.vee.

See Tell Me About > .NET Framework in the Table of Contents

Connectivity for USB Based Instruments

Keeping VEE current with the newest Agilent instrumentation and competitive software products has always been a goal for Agilent. To this end, the I/O subsystem has been enhanced to accommodate instruments with a Universal Serial Bus (USB). Another feature of USB support is the ability to use USB aliases. USB aliases replace the long and awkward address string of USB addresses.

Connectivity for LAN Based Instruments

As stated in the USB connectivity paragraph, alternative connections to instrumentation are becoming standard. To adapt to these changes, VEE has been enhanced to provide connectivity for LAN-based instruments.

Use IVI-COM Drivers

IVI-COM is the latest standard for instrument compatibility. Established by the IVI Foundation, it encourages instrument manufacturers to produce instruments that are interchangeable with their competitors. To adapt to these new standards, VEE will accept all Agilent IVI-COM drivers and some third party IVI-COM drivers as well.

VEE interacts with IVI-COM drivers by finding a Primary Interop Assembly (PIA) for them. An assembly is an .EXE or DLL file and is the fundamental building block of a .NET application. The PIA is a .NET assembly that is provided by vendors for their COM based components. Since your IVI-COM driver is a COM based component, VEE will attempt to find a PIA for it. Once this is done, VEE lets you use the IVI-COM driver just like any other .NET assembly.

See What is IVI?

The Error Reporting Mechanism has Changed

Agilent has changed the VEE error reporting mechanism. Please take advantage of this valuable facility. See Minidumps for more information.

What’s New in Agilent VEE 6.0

Welcome to the Agilent VEE software family, version 6.0. A list of new features and enhancements for version 6.0 follows. For more information about these features click "New Features" or "Enhancements." For more information about all the features in your Agilent VEE software, see the Help Contents or Index.

New Features

Multimedia Tutorials
Integrated MATLAB® Script
Callable VEE ActiveX Automation Server
New Data Types
VEE 6 Execution Mode
New Functions
VEE I/O Configuration File Saved with Program
Programmable Instrument Properties
Dynamic I/O Automation Server
Added I/O Diagnostics Features
Instrument Manager Toolbar Button
VXI 64-bit Memory Access Support
PC Plug-In Card Support
Added Program Explorer Submenu
New RunTime Option
Program Settings Stored in Registry
MAPI Email Support
Microsoft Intellimouse Wheel Support

Agilent VEE (on Windows) now includes multimedia tutorials to help you become productive even faster. Here are the easy viewing steps:

1. Put the VEE CD in the same CD drive you used when you installed VEE.
2. Run VEE and click the "Tutorials" button in the Welcome Window.
3. Watch any or all of the seven helpful tutorials.

Integrated MATLAB® Script

Agilent VEE 6.0 makes the power of MATLAB available to the VEE programmer. VEE now ships with a runtime version of MATLAB Script. There is also a new MATLAB Script object in the Device menu. All available MATLAB functions are displayed in VEE's Function & Object Browser also. (VEE does not provide MATLAB support on HP-UX.)

Callable VEE ActiveX Automation Server

Previous versions of VEE provided two ways to execute VEE code from other development environments: the C-to-VEE API and the Callable VEE ActiveX Control. Agilent VEE Pro 6.0 replaces the old ActiveX Control with an ActiveX Automation Server that allows you to easily access VEE code from programming environments like Visual Basic. (The Callable VEE Server is supported on Windows only.)

For more information, refer to the VEE CallServer Help..

New Data Types

UInt8, Int16, Real32, and Variant are new data types for Agilent VEE 6.0. All new data types appear in all Execution Modes, as well as new transactions such as WRITE TEXT INT16. However, new transactions behave the old way in old modes. For example, in VEE 5 mode, WRITE BINARY INT16 actually does a WRITE BINARY INT32 and will not convert the data to an Int16. In VEE 6 mode, WRITE BINARY INT16 does convert data to an Int16. See the Execution Mode topic for ways that VEE Execution Mode could change program behavior.

Locations

Data [image] Constant [image] UInt8
Data [image] Constant [image] Int16
Data [image] Constant [image] Real32
Data [image] Allocate Array [image] UInt8
Data [image] Allocate Array [image] Int16
Data [image] Allocate Array [image] Real32

VEE 6 Execution Mode

Version 6.0 of Agilent VEE software adds a VEE 6 Execution Mode to the Default Preferences Dialog Box. For more information, see the Execution Mode help topic.

New Functions

VEE's new data types (Int16, Real32, Variant, UInt8) help expand compatibility with ActiveX automation servers. Also, new functions make it easier to deal with other ActiveX data types that have no VEE counterpart (for example, Currency and Date). For details, see the Type Conversion help topic. The following new functions were added to the Agilent VEE 6.0 language.

asVariant()
asVariantBool()
asVariantCurrency()
asVariantDate()
asVariantError()
asVariantEmpty()
asVariantNull()
baseName(pathStr)
commandLine()
dirName(pathStr)
inDaylightSavings()
isVariant()
isVariantBool()
isVariantCurrency()
isVariantDate()
isVariantError()
isVariantEmpty()
isVariantNull()
programName()
typeName(x)

VEE I/O Configuration File Saved with Program

VEE 6.0 allows you to embed I/O configuration information in the program itself, rather than using the veeio resource file. To enable embedding of the configuration information, a Save I/O configuration with program check box has been added to the Save File Dialog Box. See Instrument Manager for more information on saving an I/O configuration.

Location: File Save (Save a new program)

File Save As (Save As)

Programmable Instrument Properties

Version 6.0 of Agilent VEE software adds the capability to change instrument parameters (such as timeout value) at runtime. This new feature obsoletes control inputs to the Direct I/O Object and allows you to Get/Set some programmatic instrument parameters at runtime. (Although the need for control inputs is eliminated, control inputs are still supported.) Available instruments and their properties are listed in the Function and Object Browser, and formulas can be created from this list.

For information on available properties, see GPIB Instrument Properties , GPIO Instrument Properties , Serial Instrument Properties , and VXI Instrument Properties . Also see these two examples:

examples\InstrumentIO\ProgrammableInstrProperty1.vee

examples\InstrumentIO\ProgrammableInstrProperty2.vee

Dynamic I/O Automation Server

In previous versions of VEE, instrument bus addresses in the VEE I/O configuration file were static (fixed). For version 6.0, the Dynamic I/O Automation Server lets you find and identify instruments programmatically. This provides new levels of flexibility. For example, you can find all your instruments and then use Programmable Instrument Properties to set up Direct I/O objects. (The Dynamic I/O Automation Server is supported on Windows only.)

See Dynamic I/O Automation Server for more information.

Added I/O Diagnostics Features

Version 6.0 adds significant new I/O diagnostics features. These features can be divided into error prevention and error recovery, primarily involving instrument checking.

Error Prevention

VEE 6.0 can perform instrument checking before the VEE program body executes. To enable instrument checking, use File Default Preferences and select the Check Instrument Addresses at PreRun box. For more information, see Default Preferences (the "Debug" group).

Error Recovery

Version 6.0 adds a Troubleshooting button to the VEE Run Time Error Dialog box when an I/O timeout error is detected. The diagnostic I/O errors caught are Error 811 - Timeout or General I/O Error.

When a VEE instrument access has failed because of a non-existent interface or unoccupied bus address, the diagnostic indicates the type of error and provides some suggestions to correct the error.

Instrument Manager Toolbar Button

Version 6.0 adds an Instrument Manager icon to the Toolbar display for easy access to the Instrument Manager Dialog Box. You can, of course, still access Instrument Manager from the menu using I/O Instrument Manager….

VXI 64-bit Memory Access Support

Agilent I/O Libraries G.02.02 supports 64-bit access to some VXI instruments’ memory space. This feature enables VEE programs to read/write memory in 64-bit units. If you have version G.02.02 (or greater) installed, you can use the A24/A32 Space tab on the Advanced Instrument Properties dialog box to enable this access mode.

Location: I/O Instrument Manager

(Select a VXI instrument) Instrument Properties Advanced... A24/A32 Space tab.

PC Plug-In Card Support

VEE 6.0 supports PC Plug-In cards with ODAA (Open Data Acquisition Association) compliant software drivers. To use these cards, install the hardware and software, then configure subsystems according to the manufacturer’s instructions. From the Agilent VEE Instrument Manager, click the Find Instruments button.

If the PC Plug-In cards are configured correctly, the Instrument Manager displays the configured subsystems. Select the desired subsystem, then click the PCPI Driver button to create a formula object. You can browse properties and methods, and can create a formula from the Function & Object Browser dialog box for the subsystems.

Added Program Explorer Submenu

In Agilent VEE 6.0, a new submenu was added for Globals in the Program Explorer. This new choice, named "Generate," provides convenient access to operations involving the Global Variable, such as Get, Set, and If/Then/Else.

New RunTime Option

The VEE Pro RunTime has a new option -enablewarnings that allows you to check your program under RunTime to make sure that you have all the necessary files. Without -enablewarnings, the RunTime product silently ignores non-fatal errors like "Picture file is missing."

Program Settings Stored in Registry

In VEE 4.x and 5.0, certain information (such as Toolbar visible, Status bar visible, etc.) was saved in the default preferences file (vee.rc). With version 6.0, these settings are no longer stored in the vee.rc file.

In addition, previous versions of VEE on Windows stored some settings in the v.ini file. VEE no longer uses a v.ini file on MS Windows. All these settings are now stored in the Windows registry on a per user basis under HKEY_CURRENT_USER\Software\Agilent\VEE.

On HP-UX, the information is stored in a file called .vee-settings and is located in the user’s $HOME directory. (That file was previously called .vee-history.)

You do not have to do anything to store the program settings, as the settings are stored automatically when VEE exits. The next time you open VEE, it appears in the same place, with the same size, and has the same user interface options selected.

MAPI Email Support

Version 6.0 adds a "Send Program by Email" File menu item for systems that have a MAPI profile. For HP-UX systems and PCs without a MAPI profile, this feature is not supported.

Location: File Send Program by Email

Microsoft Intellimouse Wheel Support

Version 6.0 adds support for the Microsoft Intellimouse. If you have a Microsoft Intellimouse or a compatible clone, rotating the mouse wheel while a list view has focus causes the list view to scroll up or down.

Enhancements

Improved Install Program
Variant to VEE Data Type Conversion – Improved Array Handling
Improved Automation Server Cleanup
Additional Graphics File Support
Improved XY Marker Properties
Smarter Creation of Transaction Pins
Get and Set Formula Buttons
Updated Functions
Improved PC Execute Object
Instrument Manager Update
Convenient Object Resizing
Additional Keyboard Shortcuts
Improved Sequence Line Color
Configuration Save Options

Improved Install Program

The new Windows install program allows you to do several things you couldn’t do with the old VEE install program. After you have installed VEE, you can run the Control Panel applet "Add/Remove Program" and select Agilent VEE. You will notice some new functionality. Not only can you Remove Agilent VEE, you can also Modify an existing installation. This allows you to install a component you originally did not install, such as Non-HP Panel Drivers. You can also remove a component that is no longer being used. The Repair option allows you to repair your installation of Agilent VEE.

Variant to VEE Data Type Conversion – Improved Array Handling

When data are returned from an ActiveX Automation Server (such as Excel) or an ActiveX control, VEE must convert the automation data types to VEE data types. With VEE 5.0, an array of Variants converted into a VEE Record. With version 6.0 (in VEE 6 Execution Mode), an array of Variants is converted into a VEE array if all elements are of the same data type. (For mixed data types, there is no change from VEE 5.0 behavior.)

If all elements of the source Safearray of Variant are of the same data type, mapping of Variant data type to VEE array data type is as follows. (Note: this feature is available in VEE 6 Execution Mode only.)

Variant array member type VEE 6.0 data type

VT_UI1 UInt8
VT_BOOL Int32
VT_I2 Int16
VT_UI2 Int16
VT_I4 Int32
VT_UI4 Int32
VT_R4 Real32
VT_R8 Real64
VT_DATE Real64
VT_CY Real64
VT_BSTR Text
VT_DISPATCH Object

Improved Automation Server Cleanup

You may have noticed that when your VEE program finished, and it used an Automation Server (like Excel), sometimes the Excel (or whatever) application did not quit. VEE 6.0 has improved handling of ActiveX references and releases all unneeded pointers. For more information about programming techniques that affect the cleanup of ActiveX references, see the CreateObject topic.

Additional Graphics File Support

Version 6.0 adds read-only capability for JPG, WMF, and PNG formats on Windows 95/98/NT. More BMP and GIF formats can be read also. Refer to the Picture object help topic.

Improved XY Marker Properties

Version 6.0 allows you to get the position of Markers as values in any expression. For details about these new properties, refer to the section titled "Programmatically Setting and Reading Marker Values" in the Help topic for any XY Display. Some examples of XY Displays are XY Trace, Magnitude Spectrum, and Polar Plot. Also see the topic: To Get and Set Marker Properties.

Smarter Creation of Transaction Pins

Objects with Transactions now automatically add inputs and outputs based on the use of terminal names in the transaction. This feature is aware of local or global variables, so pins are not added when the name refers to a local or global variable.

Get and Set Formula Buttons

The Function & Object Browser now supports creating two types of formulas for properties in the ActiveX, VEE Objects, and Instruments groups. You can create a "Get Property" formula or a "Set Property" formula by pressing the appropriate button.

Updated Functions

The following functions have been updated for Agilent VEE software version 6.0.

whichOS() Added Windows 98 and Windows 2000.

createObject() Added an optional hostname parameter.

Improved PC Execute Object

The PC Execute object now supports returning an exit code from the executed program and can use a registered suffix to run associated programs. See the Execute Program (PC) Help topic.

Instrument Manager Update

Version 6.0 makes it easier to configure instrument drivers by providing a "Configure Drivers" button in the Instrument Manager dialog box. You can select a single instrument, an interface card, or the entire I/O configuration and configure the driver(s) with one button click. For more information, see the Instrument Manager Help topic.

Convenient Object Resizing

In Agilent VEE 6.0, any object can be resized by dragging any one of its four corners. This convenience works in the panel view or the detail view.

Object Resize operations now snap-to-grid by default. The behavior is the same in Panel View and in Detail View. Grabbing a corner with an unshifted mouse click starts coarse (snap-to-grid) resizing. Grabbing a corner with a shifted mouse click starts fine (1-pixel) resizing. The grid size is fixed at 10 pixels in Detail View and defaults to 10 pixels in Panel View.

In VEE 5.0, snap-to-grid was the only behavior in Panel View, and fine resizing was the only behavior in Detail View.

Additional Keyboard Shortcuts

There are some new mappings for function keys to aid in debugging:

F5 maps to "Run" as does Ctrl-G

F10 maps to "Step Over"

F11 maps to "Step Into"

Shift-F11 maps to "Step Out"

See Using Keyboard Shortcuts for a complete list of VEE shortcut mappings.

Improved Sequence Line Color

In Agilent VEE 6.0, all lines connected to a sequence input are one-pixel wide and light gray, which allows lines that are actually carrying program data to stand out. (A majority of VEE program lines typically designate sequence, not data.)

Configuration Save Options

In Agilent VEE 6.0, "Save colors/fonts with program" and "Save Device Configuration" have been removed from the "Default Preferences" dialog box, and the following options have been added to the "Save File" dialog box:

Options

[ ] Save colors and fonts with program

[ ] Save I/O configuration with program

See Save As for more information about using the save options.

Location: File Save As…

What is New in HP VEE 5.0

Thank you for using HP VEE. Many features in this version are new or have changed from previous versions, and this section of HP VEE Help describes them for you. Scroll through the topics below for a summary of what's new, and an introduction to compatibility issues with your existing programs. Click on the links to get more information about using these features. For detailed information about these and all other existing features in HP VEE, see the HP VEE Help Contents or Index.

The HP VEE Web site contains support information, instructions for downloading instrument drivers, and many other helpful resources. You can link to our site from the HP VEE window using Help => HP VEE on the Web.

Note

The save file format changed after HP VEE 3.x. If you save your HP VEE 3.x program in HP VEE 4.0 and later, you will not be able to open it in HP VEE 3.x and earlier.

The save file format remained the same from HP VEE 4.x to HP VEE 5.0. However, your programs may not run correctly if you move them between the two versions. For example, if you open your HP VEE 4.x program in HP VEE 5.0 to use new features, then save the program, you can open it again in HP VEE 4.x. However, the new features will be removed, and may corrupt the program.

ActiveX Support HP VEE for Windows supports ActiveX automation and controls on PCs running Windows® 95/NT® 4.0 or greater (not supported on UNIX).

ActiveX automation lets you use HP VEE as an Automation Controller. This lets you control other applications such as Microsoft® Word, Excel, and Access for activities such as sending data to the applications for report generation. This fully supersedes our current application control solution, Dynamic Data Exchange (DDE), for automation-capable applications.

ActiveX controls, available from various vendors, extend HP VEE's functionality by providing domain-specific services via ActiveX automation properties, methods and events. Most ActiveX controls also provide a user interface that let you manipulate a control such as a Calendar to initiate events based on calendar dates.

Web Monitoring HP VEE includes a built-in Web server letting you monitor and troubleshoot an HP VEE application from a remote Web browser using standard HTTP protocol. You can use this feature to

  • Troubleshoot a system running on the factory floor.

  • Retrieve information from an HP VEE program.

  • Monitor a test system.

HP VEE Objects and Functions

XY Displays contain several enhancements that let you define scale labels and their spacing, and set number formats.

Knob, Slider and Indicator Objects contain enhancements that let you select logarithmic or linear scaling, set number formats, and control tic mark labels and their spacing.

Formula Object now accepts expressions in multiple lines. When you enter one or more expressions, you can have one expression per line, or split the expression(s) over multiple lines.

UserFunction Menu choices let you automatically generate calls to UserFunctions from the objects and functions most frequently used for calling UserFunctions: Call, Formula, If/Then/Else, showPanel(), and hidePanel().

SavePanelImage Function allows programmatic rendering of an HP VEE UserFunction panel to a file letting you dynamically embed an HP VEE panel in a report.

Development Environment

The HP VEE Development Environment contains several changes including

  • Execution Mode has changed to Compatibility Mode in the Default Preferences dialog box; modes are VEE 3, VEE 4, and Standard.

  • Select Function dialog box is now Function & Object Browser (Device menu). It is Function Browser on UNIX.

  • Expanded Clipboard support lets you copy object bitmaps from HP VEE to other Windows applications

  • .vxe binary file format for smaller files and better security for RunTime programs.

  • Better access to online Help information.

Instrument Manager

The button labels on the Instrument Manager dialog box have been changed. The Configuration areas button labels will change dynamically depending on which node is selected in the Instrument List tree view. This gives better information about configuration changes allowed for each node. For more information, see Instrument Manager .

ActiveX Support

HP VEE for Windows supports ActiveX automation and controls on PCs running Windows 95/NT 4.0 or greater (not supported on UNIX).

Note

To enable ActiveX support, HP VEE must be set to Standard mode in the Default Preferences dialog box on the General tab. This is the default mode for new programs. See the "Execution Mode" section in Development Environment for details about changes to menus, objects, and functions when HP VEE is set to Standard mode.

ActiveX Automation lets you use HP VEE as an Automation Controller. This lets you control other applications such as Microsoft Word, Excel, and Access for activities such as sending data to the applications for report generation. This fully supersedes our current application control solution, Dynamic Data Exchange (DDE), for automation-capable applications.

ActiveX Controls, available from various vendors, extend HP VEE's functionality by providing domain-specific services via ActiveX automation properties, methods and events. Most ActiveX controls also provide a user interface that let you manipulate a control such as a Calendar to initiate events based on calendar dates.

Recommended Reading

Microsoft Office 97 Visual Basic Programmer's Guide
Microsoft Press, 1997
ISBN 1-57231-340-4

HP VEE implements its ActiveX support using the standard established by Microsoft Visual Basic. If you are unfamiliar with ActiveX technology, review the chapters in this book that discuss Object Models, and ActiveX Controls. Understanding these concepts will help you use HP VEE's ActiveX features.

Read the chapter "Using ActiveX Automation Objects and Controls" in the HP VEE Advanced Programming Techniques manual to learn how to use ActiveX in HP VEE. Many new example programs have been added to the \examples directory. To open them from the HP VEE window, use Help => Open Example. They are under \ActiveXAutomation and \ActiveXControls.

Web Monitoring

HP VEE includes a built-in Web server letting you monitor and troubleshoot an HP VEE application from a remote Web browser using standard HTTP protocol. You can use this feature to

  • Troubleshoot a system running on the factory floor.

  • Retrieve information from an HP VEE program.

  • Monitor a test system.

You can enable the Web server by using the new Web Server tab on the Default Preferences dialog box. For this feature to work, HP VEE must be running on a system that is connected to a network. To remotely monitor the program from a Web browser, you must know the system's host name. For detailed information see Default Preferences.

HP VEE Objects and Functions

XY Displays contain several enhancements that let you define scale labels and their spacing, and set number formats. These changes appear in their Properties dialog boxes. Here is a summary of the changes. For details, see the Help topic for any display object such as XY Trace. Each display may contain some variations to support its configuration.

  • You can set the XY display background color of an individual display object in the Properties dialog box on the Colors tab. Changing the color in the Display area of the tab overrides the default color set in Default Preferences.

  • Information about traces and scales has changed on the display object's open view. The editable fields for traces and scales have changed to flat buttons. The scales' major tic marks are now labeled, and the min/max values cannot be edited on the open view.

To edit properties, click on a trace or scale name on the open view to pop up an Edit dialog box. Or, double-click the object's title bar to use the Properties dialog box; you'll notice that Traces and Scales button is gone from the General tab, and there are two new tabs, Traces and Scales.

Traces properties have not changed from HP VEE 4.x.

Scales properties have changed. Now, you can edit the min/max values only with the other properties, and two more properties are available - Label Spacing and Automatic Scaling. The properties for each scale (including the additional right scales) can be set individually.

To set the label spacing on major tic marks, click on the down-arrow by Label Spacing and click on your choice. For new programs, the default setting for X scale is Every Major Tic, and Every Other Tic for Y-Main scale. For older programs, the default is Only Max & Min to maintain a similar appearance to older style display objects.

You can set the label font separate from the object font in the display object Properties dialog box in the Fonts tab. Changing the font in the Scale Label area of the tab overrides the default font set in Default Preferences. The label color tracks the object text color set in Default Preferences or in the object Properties dialog boxes.

Autoscale properties have changed, and now includes an Automatic Scaling mode. The Auto Scale button on the open view is optional. You can show or hide the button in the Properties dialog box, on the General tab, in the Layout area. You can set the Automatic Scaling mode while setting other properties for the X and Y-Main scales. When Automatic Scaling is On, the scale automatically "auto scales" to incoming data. Additional right scales (Y2 and Y3) track Y-Main. This mode is not supported for the Strip Chart.

For older programs with existing display objects, Automatic Scaling is Off and the Auto Scale button appears in the open view to maintain a similar appearance to older style display objects. New display objects added to older programs use the default setting: both X and Y-Main set with Automatic Scaling mode On, and no Auto Scale button.

The control inputs for Auto Scale X, Auto Scale Y, and Auto Scale remain unchanged. The Scales control input record now accepts a new text field named AutoScale that accepts the values On or Off. This allows programmatic access to the Automatic Scaling. This is not supported for the Strip Chart.

  • You can set the number format for each scale in the Properties dialog box on the Number tab.

The Marker values use the same number format as the scale to which they are attached. The Delta Markers for the X and Y scales use the default number format set in the Default Preferences dialog box. However, if both Marker1 and Marker2 on the X or Y scales are using Time Stamp format, the Delta Marker uses Delta Time format.

  • The Layout area on the General tab of the Properties dialog box has changed. The new options give you greater flexibility for controlling the open view's appearance and security:

    • Show Traces Legend turns the Trace edit buttons on and off.

    • Show Scales Legend turns the X and Y scale edit buttons on and off.

    • Show Scale Labels turns the axis scale labels on and off.

    • Show Scroll Bars turns the scroll bars on and off.

    • Show Auto Scale Button turns the Auto Scale button on and off.

    • Enable Trace/Scale Editing controls the edit function of the Trace and Scales edit buttons.

Knob, Slider and Indicator Objects

Contain enhancements that let you select logarithmic or linear scaling, set number formats, and control tic mark labels and their spacing. These enhancements specifically affect the Integer/Real Knob and Slider, Meter, Thermometer, Fill Bar and Tank objects. The Color Alarm adds only the number format control. All of these changes appear in the Properties dialog box for each object.

  • You can choose between linear and logarithmic scaling on the General tab, in the Scale area. Logarithmic scaling is not supported for the Integer Knob/Slider objects.

  • You can set the label spacing for major tic marks on the General tab in the Scales area. Click on the down-arrow by Label Spacing and click on your choice.

  • You can turn tic marks and labels on and off in the Knob, Thermometer, Fill Bar and Tank objects. This was allowed previously only in the Slider and Meter objects.

  • A Number formats tab has been added to the Thermometer, Fill Bar, Tank, and Color Alarm Properties dialog box. Now, these objects, like the Knob, Slider, and Meter, will display their min/max and tic label values in the current number format.

  • For detailed information see Integer KnobInteger_Knob, Integer SliderInteger_Slid, Real KnobReal_Knob, Real SliderReal_Slider, Fill BarFill_Bar, MeterMeter, TankTank, ThermometerThermo.

Formula Object now accepts expressions in multiple lines. This lets you expand the Formula object vertically and horizontally when entering long expressions. Formula objects in older programs opened in this HP VEE version will follow this new behavior. When you enter one or more expressions, you can have one expression per line, or split a single expression(s) over multiple lines as shown in the following example.

(a == someLongExpr

? "return someLongTrue"

: "return someLongFalse"

)

  • A carriage return (\r) is added as the separator at the end of each line; it is not visible. The parser checks for a valid expression when the Formula object loses focus. In the next two examples, the first expression causes a syntax error because it appears that a variable name has been split. The resulting error message points to the error location:

2 * A +

3 - foo

bar - snafu

The next example fixes the problem by adding an operator after foo:

2 * A +

3 - foo -

bar - snafu

  • Control inputs to a Formula object now accept Array or Scalar Text.

  • Editing Features have been added to Formula so you can edit multiple lines of expressions more easily.

  • For detailed information see FormulaFormula_Object>main.

On the UserFunction Menu, the Generate menu pick cascades to include more choices to let you automatically generate calls to UserFunctions from the objects and functions most frequently used for calling UserFunctions: Call, Formula, If/Then/Else, showPanel(), and hidePanel(). Previously, only the Call object was automatically generated. The additional menu picks let you generate calls to UserFunctions from more appropriate objects, such as referencing a Boolean function with an If/Then/Else object, or controlling your program's appearance using the showPanel() or hidePanel() function. Access to the Generate menu pick remains the same.

  • In the Program Explorer, click the right mouse button on a UserFunction name.

  • In a UserFunction window, use the object menu.

  • For detailed information see UserFunctionUser_Function>main.

The savePanelImage() Function allows programmatic rendering of an HP VEE UserFunction panel to a file. This lets you dynamically embed an HP VEE UserFunction panel in a report. UserObject panels are not supported. The savePanelImage() (Device => Function & Object Browser) is located with the Built-in Functions in the Panel Category. A Formula object performs the function call. Graphics formats supported by savePanelImage() include Windows Bitmap (Windows only) and JPEG (Windows and UNIX). For detailed information, see savePanelImage().

Development Environment

Execution Mode has changed to Compatibility Mode in the Default Preferences dialog box on the General tab. Supported modes are Standard, VEE 4, VEE 3. Also, the Disable Debug Features checkbox moved to the Debug area. The VEE 4 and VEE 3 modes retain their compatibility definitions set in HP VEE 4.x. There are minor changes, described below, that will not affect your existing programs if you continue running them in their original modes.

The new Standard mode is a superset of the VEE 4 mode and introduces some significant changes affecting program compatibility. Most of the changes enable the new ActiveX automation features, and they may impact your programming techniques if you use any of the features described below - even if you do not use ActiveX. For information about ActiveX automation and controls, see ActiveX Support.

New HP VEE 5.0 programs will open in Standard mode. Older programs must be changed manually to the new mode, if desired, in Default Preferences. When you change a program to Standard mode, errors can occur, and a list appears of things that are no longer allowed. You need to fix these before HP VEE accepts the switch to Standard mode. HP VEE does not automatically revise any part of your program to fix the errors. A summary of the Standard mode compatibility changes are described below that will help you fix errors.

Note

For detailed information about Compatibility Mode, you are encouraged to read the appendix "Using the Compatibility Mode" in the HP VEE Advanced Programming Techniques manual. If you want to change HP VEE 3.x programs to Standard mode, you should be sure they work in VEE 4 mode first, then change them to Standard mode.

Changes for Standard mode include:

  • HP VEE programs are compiled.

  • In the Formula object:

    • SET and ByRef are new keywords used for ActiveX automation, and cannot be used as names for terminals.

    • New syntax is supported for ActiveX automation such as excel.worksheets(1).cells(1,2) = 2.

    • Entering array syntax without commas, such as [1 2 3] will cause an error when Formula loses focus.

    • A value such as 1 returns an Integer, 1.0 returns a Real. Previously, both returned a Real.

    • There are two new built-in functions for ActiveX automation: CreateObject() and GetObject().

  • When Delete Variables at PreRun is turned on (in Default Preferences) global variables are not deleted if they reference ActiveX controls.

  • The Declare Variable object has a new variable type called Object for ActiveX automation.

  • The new Object variable type is also available on Input Terminals as a Required Type, though it can't be coerced.

  • The Device menu contains new menu items: ActiveX Automation References…, ActiveX Control References…, and ActiveX Controls.

  • Global namespace rules have changed:

    • Local UserFunctions, Library names, global declared and undeclared variables, and local to library declared variables are all in the same namespace, and must have unique names. So you can't have a UserFunction and a declared global variable with the same name.

    • In a Library, local UserFunctions and local-to-library declared variables are in the same namespace and must have unique names.

  • READ TEXT transactions in objects such as To String and From String have changed how the read pointer behaves when using the TOKEN format with EXCLUDE CHARS. Now, after a READ TEXT transaction, the pointer advances to the next non-excluded character, ready for the next transaction. In VEE 3 and VEE 4 mode, the pointer stops at the excluded character.

  • In VEE 3 and VEE 4 modes, a program using a To File or From File object with the EXECUTE REWIND transaction to access the same data file as a To DataSet or From DataSet object causes unexpected interactions, where data can be written incorrectly. In Standard mode, this unexpected interaction is fixed so the data is written to the file correctly.

Changes for all modes include:

  • When older programs are opened, they will be in VEE 3 or VEE 4 mode depending on how they were saved. Expressions with array syntax, such as [1 2 3] (without commas) will be reparsed when the program loads and automatically modified to use commas.

  • New syntax is allowed in the Formula object, such as lib.func(a,b) = RightHandExpr

This parses correctly in all modes, and executes correctly only in Standard mode (errors at run time in VEE 4 and VEE 3). This lets you fix global namespace problems with imported libraries when changing modes.

  • UNIX programs can be put into Standard mode. This affects the global namespace as described above. However, the ActiveX menu items will not appear since they are not supported on UNIX. A program that calls HP VEE functions supporting ActiveX, such as CreateObject(), will error. Standard-mode programs with declared Object variable types will load into UNIX, but they will not run properly.

Select Function

This dialog box is renamed to Function & Object Browser (Device menu) to include ActiveX automation and controls support with the existing math operators and functions. On UNIX, it is Function Browser. For more information see Function and Object Browser , and "Using ActiveX Objects and Controls" in HP VEE Advanced Programming Techniques.

Expanded Clipboard support

Lets you cut/copy/paste objects from HP VEE to other Windows applications that support bitmap rendering. This is in addition to the current support letting you cut/copy/paste objects only within and between HP VEE sessions. Select one or more objects you want to cut or copy, then use the HP VEE Edit menu or the toolbar to render the object(s) into the Clipboard. The Copy menu item has also been added to the UserObject and UserFunction object menu.

Greater RunTime program security

This is available for .vxe files. You can now save a RunTime version of your program in binary mode for smaller file size and better program security (File => Save Secured RunTime Version). In Default Preferences on the General tab, the Binary RunTime File Format option is checked by default. Uncheck the box to save the file in ASCII. For added security, HP VEE no longer merges .vxe files into another program, whether or not the .vxe was saved in the binary format. HP VEE will still import libraries saved as .vxe files.

HP VEE Help

Offers easier access to information:

  • Help on objects in a program is accessible by pressing the F1 key when HP VEE is not running. In a program's Detail View, press F1 to get the Help topic for the last-selected object. Otherwise, the HP VEE Help Contents window appears.

  • The Help menu now includes links to useful Web sites (Windows only).

  • The HP VEE Help Contents window contains the new heading Guide to HP VEE Example Programs. It contains summaries about the examples shipped with HP VEE, with links that open examples directly from the Help.


Overview

With VEE, you can control instruments in several ways:

• The Direct I/O object allows you to transmit commands and receive data over many supported interfaces.

• VXIplug&play drivers can be used to call C functions to control instruments. These are provided by Agilent Technologies and other vendors with their supported instruments.

• NI Data Acquisition libraries can be used to control instruments connected to National Instruments PXI/PCI cards. Some SCXI support is also provided.

• “Panel” drivers give you a simple user interface (or “front panel”) to control an instrument from your computer screen. When you change parameters in the VEE panel driver, the corresponding state of the instrument is changed. Panel drivers are provided by Agilent Technologies with VEE and cover over 450 instruments from different vendors.

• I/O libraries can be imported to control PC Plug-in boards and then call functions from that library using the Call object. These libraries are usually shipped as Dynamic Link Libraries (DLLs).

Panel Drivers

Agilent VEE includes over 450 panel drivers for different instrument vendors. A panel driver works by using a display in the VEE program that controls the settings in the corresponding physical instrument. Panel drivers provide maximum ease-of-use and save the most development time. Following figure is an example of a panel driver.

PC Plug-in Boards with I/O Library

I/O libraries, usually shipped as Dynamically Linked Libraries (or DLLs) for PC Plug-in boards, are supplied by the vendor of the PC Plug-in board. VEE enables you to control the PC Plug-in board by calling library functions with the Call object. Following figure shows an example of the Import Library object that makes the functions available in VEE.

NI Data Acquisition Libraries

National Instruments’ Data Acquisition libraries are accessible from within VEE. The supported libraries are niDMM, niSWITCH, niFGEN, niSCOPE, niDQAmx, and niDAQ. See following figure for an example of an niDMM ConfigureMeasurement transaction in VEE.

VXIplug&play Drivers

VXIplug&play drivers are supplied by the instrument vendor or by Agilent Technologies. (For a list of VXIplug&play drivers available from Agilent Technologies, refer to the VEE literature or Introduction to VXIplug&play. Contact your instrument vendor for other VXIplug&play drivers.) VEE enables you to control an instrument with a VXIplug&play driver by making calls to the driver. The following figure is an example of calls to a VXIplug&play driver from VEE.

Other I/O Features

1 Explore the full power of VEE's I/O capabilities in the I/O [image] Advanced I/O submenu: Interface Operations, Instrument Event, Interface Event, and MultiInstrument Direct I/O.

2 You can display, print, or store bus activity for debugging with the Agilent IO Monitor in the I/O menu.

3 VEE includes an ActiveX Automation server to programmatically find instruments.

4 You can also change I/O configurations programmatically at run time.

See Also

Configuring an Instrument

Using a Panel Driver

Using Direct I/O

Using PC Plug-in Boards

Using NI Data Acquisition in VEE

IVI-COM and the Instrument Manager

Using a VXIplug&play Driver

Using ActiveX Automation in VEE


ActiveX Automation in Agilent VEE

The term ActiveX Automation refers to VEE’s ability to act as an Automation Controller of Automation Server applications such as MS Excel, MS Word, and MS Access. The exercises focus on the practical application of Microsoft’s ActiveX technology to generate test and measurement program reports.

See Also: Lab 6-1: Sending Agilent VEE Data to MS Excel

Lab 6-2: Creating an Agilent VEE to MS Excel Template

Lab 6-3: Using MS Word for Agilent VEE Reports


Supported I/O Interfaces

The following table lists the supported I/O interfaces for each platform.

Platform | Supported I/O Interfaces
Windows Vista, Windows 2000 and Windows XP | GPIB, Serial,GPIO, USB, TCP/IP, NIDAQ, VXI


Code Completion

To Use Code Completion

Code Completion provides quick access to valid members, properties, or variables via the Code Completion window (as shown below).

To Trigger Code Completion

  • Automatically Trigger Code Completion

  1. Code Completion window will appear automatically listing all available choices and their brief descriptions while you are typing in a Formula box. This is called Instant Completion.

Available choices for Instant Completion include

        • Variables (Global, Local to Context, Local to Library)

        • VEE Constants

        • Terminals (Including input terminals and output terminals of the current Formula object. Output terminal "Result" is not included.)

        • Built-in functions

        • .NET namespaces and classes

        • COM Constants

  2. When a "." is typed after the name of an object (VEE objects like OK Button, Toggle controls, .NET objects, COM objects, etc) in a Formula object, a Code Completion window appears automatically listing all members or properties for that object. Here is an example of the Code Completion window. arraylist is a .NET Object. All members of arraylist are listed in the Code Completion window.

When you set the Declared Name property of a VEE Object (e.g., OK button, Label, etc), the Properties of that VEE Object will also be listed in the Code Completion window. For detailed information on the Declared Name property, see Programmatic Properties .

  3. When you use '=' to set color property for a named object, or use '=' to set value for a COM object’s property which is a pre-defined COM Constant, or use '=' to set value for a .NET object’s property which is of enumeration type. Code Completion window appears after '=' is typed, listing all the available choices. In the following figure, XYSin is a named object. All properties are listed in the Code Completion window.

In the following figure, g_ActiveMovie is a COM object. Its property Appearance is a COM constant. The Code Completion window appears after '=' is typed.

In the following figure, Button is a .NET object. Its property Anchor is of enumeration type. The Code Completion window as well as namespace appear after '=' is typed.

  • Manually Trigger Code Completion

With the edit cursor in the formula field, pressing "Ctrl + SPACE" will trigger the Code Completion window. All available choices will be listed in the Code Completion window. No Code Completion window appears if there is no available choice currently. In the following figure, the Code Completion window appears if "Ctrl + SPACE" is pressed.

All available Variables and .NET namespaces will be listed if a Code Completion window is triggered in the middle of typing a variable name or namespace name.

To Complete the Code

With the Code Completion window displaying, double clicking a choice, hitting the Tab key, or hitting the Enter key with that choice selected will choose the choice to complete the expression. You can also type in the choice manually. In this case, the closest matching choice will be highlighted while you are typing. In the following figure, when Con is typed, Contains is highlighted. A brief description of a choice will be shown when the choice is selected.

.

note

VEE Code Completion is enabled by default. You can disable it at File => Default Preferences, under General Tab.

In the Default Preferences dialog box, you can enable or disable the Code Completion support for built-in functions or COM Constants too.

See Also

Code Insight


Code Insight

When you are typing a function in a Formula object, Code Insight displays a Code Insight window containing the complete function prototype, including parameters. The Code Insight window is also displayed for nested functions.

To Trigger Code Insight

When an open parenthesis is entered after a function name (e.g., the name of a VEE UserFunction, a .NET method, etc) in a Formula object, a Code Insight window (i.e., the yellow Tool-tip) appears. The complete function prototype, including return values and parameters, will be listed in the Code Insight window. The detail level of the Code Insight window varies, for example, the description details for a .NET function will appear only when the .NET assembly comes with its own XML documentation file. The current parameter is displayed in BOLD. See the following figure:

"2 of 9 METHOD Int32 IndexOf (System.Char value)" is displayed in the Code Insight window.

'2 of 9' means there are nine methods having the same name "IndexOf", and this is the second one. To explore all the nine methods, press UP or Down arrows in the Code Insight window. Int32 is the Return Value. There is one parameter in this method.

To dismiss Code Insight window

With Code Insight window displaying, press ESC at any time to dismiss the Code Insight window, or type the closing parenthesis. Moving cursor across a comma or the leftmost open parenthesis also dismisses this window.

If you dismiss the Code Insight window before completing the function and wish to view it again, press CTRL+SHIFT+SPACE.

NOte

The Code Insight feature is enabled by default. You can disable it in File [image] Default Preferences, under General Tab.

Objects Supported by Code Insight

  • Methods of .NET Objects

  • Local UserFunctions

  • Imported UserFunctions

  • Built-in Functions

  • Imported Remote Functions

  • Imported Compiled Functions

  • COM Objects

See Also

Code Completion


Keywords Constants

Keywords and Constants in VEE

Keywords

Keywords are reserved by Agilent VEE and cannot be used to name your objects or terminals, or used in IO transactions .

The following table lists all Keywords which cannot be used to name your objects or terminals.

AND | ASAWF | ASBOOLEAN | ASCOMPLEX | ASCOORD
ASDOUBLE | ASFS | ASINT | ASINT16 | ASINT32
ASINT64 | ASINTEGER | ASLONG | ASLONGINT | ASPCOMPLEX
ASREAL | ASREAL32 | ASREAL64 | ASSHORT | ASSPECTRUM
ASSTR | ASSTRING | ASTEXT | ASUINT8 | ASWAVEFORM
Builtin | ByRef | COORD | DIV | Main
MAXINT | MAXINT16 | MaxInt16 | MAXINT32 | MaxInt32
MAXINT64 | MaxInt64 | MaxLong | MAXLONG | MaxShort
MAXSHORT | Me | MinInt | MININT | MININT16
MinInt16 | MinInt32 | MININT32 | MinInt64 | MININT64
MOD | NOT | OR | PI | SET
XOR | XYZZY |  |  |

The following table shows all Reserved Words which cannot be used in IO transactions.

ABORT | ACK | ALL | ARRAY | BEL
BINARY | BINBLOCK | BOOL | BOOLEAN | BREAK
BS | BYTE | CAN | CASE | CHAR
CLEAR | CLOSE | CLOSEREAD | CLOSEWRITE | CMD
CMND | CONTAINER | COORD | COUNT | CPX
CR | CTL | CTS | DATA | DATAREADY
DATE | DC1 | DC2 | DC3 | DC4
DCL | DEG | DELETE | DELTIME | DLE
DMY | DSR | DTR | ECL | EM
ENQ | EOI | EOL | EOT | EQUAL
ERR | ESC | ETB | ETX | EXCLUDE
EXECUTE | EXT | FF | FIX | FS
FW | GET | GRAD | GS | GTL
H12 | H24 | HEX | HM | HMS
HT | INCLUDE | INCR | INT | INT16
INT32 | INT64 | INTERVAL | IOCONTROL | IOSTATUS
ITEM | LF | LISTEN | LJ | LLO
LOCAL | LOCALLOCKOUT | LOCK | MASK | MAXFW
MEM | MLA | MSG | MTA | NAK
NOEND | NOP | NUL | OCT | OF
OFF | ON | PASS_CONTROL | PCTL | PCX
PPC | PPU | PREFIX | PULSE | QSTR
RAD | READ | REAL | REAL32 | REAL64
REG | REMOTE | RESET | REWIND | RJ
RS | SCI | SDC | SEC | SEND
SET | SI | SIGN | SO | SOH
SPD | SPE | SPEC | SPOLL | STATE
STD | STR | STS | STX | SUB
SYN | TALK | TCT | TEXT | TIME
TOKEN | TRIGGER | TTL | UNL | UNLOCK
UNT | US | VT | WAIT | WDMY
WF | WRITE | RTS |  |

Note

By Default True and False are considered as Boolean data. It is not recommended to use True and False as object name.

Constants

The following table lists Constants in Agilent VEE and their values:

Constants | Value
MaxInt | 2147483647
MinInt | -2147483648
MaxInt16 | 32767
MinInt16 | -32768
MaxInt32 | 2147483647
MinInt32 | -2147483648
MaxInt64 | 9223372036854775807
MinInt64 | -9223372036854775808
MaxLong | 2147483647
MaxShort | 32767
PI | 3.142


NI-DAQmx

Beginning with VEE version 8.0, VEE supports for the National Instruments NIDAQmx library.

The VEE NI-DAQmx driver operates similarly to the other VEE NIDAQ drivers -- NI-DMM, NI-SCOPE, NI-SWITCH, NI-FGEN and Traditional NIDAQ. A To/From NI-DAQmx transaction object gives access to most of the functions in the National Instruments NI-DAQmx Library. These transactions have a one-to-one correspondence to the functions listed in the National Instruments NI-DAQmx C Reference Help file. Pressing the "Function Help" button while browsing the transaction list will send you to the help page for that function. It is assumed that one is familiar with programming to the NI-DAQmx API and understands the National Instruments DAQmx "Physical Channel Syntax".

The VEE NI-DAQmx driver differs from the other VEE NIDAQ drivers in a crucial way. While the other drivers are "hard-linked" to a particular device in the VEE Instrument Manager, the NI-DAQmx library is not. The NI-DAQmx transactions allow you to enter NI "Physical Channel Syntax" which allows you to program multiple devices/ports in the same transaction object. For this reason, the defaults offered for the "Physical Channel" parameter (like "Dev1/Line0") are more for instructional purposes (to tell you what kind of string the parameter is looking for). It is up to the user to be familiar enough with the National Instruments DAQmx "Physical Channel Syntax" and their available instrumentation for you to enter the appropriate string.

See Also

To/From NIDAQ, NI-FGEN, NI-SCOPE Fetch/Read Functions, Using NI Data Acquisition in VEE


Visafication

Standardize on VISA Style Devices

Phase out older inconsistent I/O devices (mixed SICL & VISA) for a more uniform approach (VISA) when declaring/using I/O devices. Backward compatibility is maintained, even though users are "encouraged" to use new-style devices.

Instrument Manager will only find instruments set up in ACE (Agilent Connection Expert) except NIDAQ devices. Once you have done the necessary configuration work for an instrument in ACE, pressing Find Instruments in VEE Instrument Manager will find this instrument without any further configuration as long as the instrument is connected.

By default, Agilent VEE 8.0 will not add SICL-style devices into the Instrument Manager. To find the legacy devices, check the Enable Pre 8.0 Legacy IO item under the IO tab in the Default Preference dialog box.

Note

In Agilent VEE 7.5, using Find Instruments in Instrument Manager will always find Serial interface. In Agilent VEE 8.0, the Serial interface will only be found when there is a serial device connected.

See Also

Instrument Manager